This section is meant to be an overview to the concepts of ParentAlignment and ChildAlignment.
For more detailed examples, check this section.
+The parent alignment is the first configuration required for aligning views in DpadRecyclerView.
+This configuration will take care of calculating the anchor position for your ViewHolders.
Consider the following example for a vertical DpadRecyclerView:
The red circle is centered both horizontally and vertically and serves as the anchor for all ViewHolders.
+To create this configuration, you would do the following:
+ +You can also create a top anchor:
+
In this case, the configuration would be:
+ +Both offset and fraction 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.
By default, the views at the minimum and maximum edges won't be aligned to the keyline position specified by ParentAlignment. If you want to change this behavior, you need to change the edge argument of ParentAlignment:
ParentAlignment.Edge.NONEParentAlignment.Edge.MINParentAlignment.Edge.MAXParentAlignment.Edge.MIN_MAXThe ChildAlignment class will take care of calculating the anchor position for your ViewHolder views.
Consider the following example for a horizontal DpadRecyclerView:
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:
+ +For more detailed examples, check the recipes section.
+ + + + + + + + + + + + + +Similar to DpadComposeViewHolder, but sends the focus down to composables
This allows inline definition of ViewHolders in onCreateViewHolder:
override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): DpadComposeFocusViewHolder<Int> {
return DpadComposeFocusViewHolder(parent) { item, isSelected ->
ItemComposable(item, isSelected)
}
}To update the current item, override onBindViewHolder and call setItemState:
override fun onBindViewHolder(holder: DpadComposeFocusViewHolder<Int>, position: Int) {
holder.setItemState(getItem(position))
}A basic ViewHolder that forwards content to a ComposeView and handles focus and clicks inside the View system.
Focus is kept inside the internal ComposeView to ensure that it behaves correctly and to workaround the following issues:
Focus is not sent correctly from Views to Composables: b/268248352 This is solved by just holding the focus in ComposeView
Clicking on a focused Composable does not trigger the standard audio feedback: b/268268856 This is solved by just handling the click on ComposeView directly
This allows inline definition of ViewHolders in onCreateViewHolder:
override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): DpadComposeViewHolder<Int> {
return DpadComposeViewHolder(parent) { item, isFocused ->
ItemComposable(item, isFocused)
}
}To update the current item, override onBindViewHolder and call setItemState:
override fun onBindViewHolder(holder: DpadComposeViewHolder<Int>, position: Int) {
holder.setItemState(getItem(position))
}Similar to ViewCompositionStrategy.DisposeOnDetachedFromWindowOrReleasedFromPool but skips releasing compositions when detached from window. This is useful for re-using compositions a lot more often when scrolling a RecyclerView.
If you use DpadRecyclerView.setRecycleChildrenOnDetach, this will behave exactly the same as ViewCompositionStrategy.DisposeOnDetachedFromWindowOrReleasedFromPool.
If you use DpadRecyclerView.setExtraLayoutSpaceStrategy, please profile the compositions before considering using this strategy.
Similar to ViewCompositionStrategy.DisposeOnDetachedFromWindowOrReleasedFromPool but skips releasing compositions when detached from window. This is useful for re-using compositions a lot more often when scrolling a RecyclerView.
Similar to Modifier.clickable, but triggers a sound effect on click. Workaround for: https://issuetracker.google.com/issues/268268856
Similar to DpadComposeViewHolder, but sends the focus down to composables
A basic ViewHolder that forwards content to a ComposeView and handles focus and clicks inside the View system.
Similar to Modifier.clickable, but triggers a sound effect on click. Workaround for: https://issuetracker.google.com/issues/268268856
Useful ViewActions for DpadRecyclerView. For other ViewAction, check DpadViewActions
Similar to RecyclerViewActions.scrollToHolder, but instead of invoking scrollToPosition, it injects KeyEvents to simulate real DPAD events from the user
Similar to RecyclerViewActions.scrollToHolder, but instead of invoking scrollToPosition, it injects KeyEvents to simulate real DPAD events from the user
Similar to RecyclerViewActions.scrollToHolder, but instead of invoking scrollToPosition, it injects KeyEvents to simulate real DPAD events from the user
Similar to RecyclerViewActions.scrollToHolder, but instead of invoking scrollToPosition, it injects KeyEvents to simulate real DPAD events from the user
Note: this will only work if there's something else in your View hierarchy that can take focus
Useful ViewAction for plain views
Note: this will only work if there's something else in your View hierarchy that can take focus
Useful ViewActions for DpadRecyclerView. For other ViewAction, check DpadViewActions
Useful ViewAction for plain views
a Matcher for a view that's inside a RecyclerView.ViewHolder at position position
Replaces Rect for unit testing purposes
Views that haven't been laid out yet will have this in spanIndex and spanGroupIndex
Views that haven't been laid out yet will have this in spanIndex and spanGroupIndex
Anchor alignment position. Always applied from start to end
Anchor alignment position. Always applied from start to end
Current span group index (row index) as of the latest layout pass
Current span group index (row index) as of the latest layout pass
A RecyclerView.LayoutManager that builds the layout around a pivot view.
It behaves similarly to GridLayoutManager with the main difference being how focus is handled.
A RecyclerView.LayoutManager that builds the layout around a pivot view.
An item decoration that applies a spacing to all sides of a view part of a grid.
default spacing between items that share a span group.
spacing between items across different span groups. Default is itemSpacing if not specified.
spacing between the start and end edges in the layout orientation. Default is itemSpacing if not specified.
An item decoration that applies a spacing to all sides of a view part of a Column or Row layout.
spacing between items in the layout direction
spacing between the start and end edges in the layout orientation. Default is itemSpacing if not specified.
spacing between the edges perpendicular to the layout orientation. Default is 0.
A base RecyclerView.ItemDecoration that checks if spacing should be applied for a given position using DpadSpacingLookup.
Subclasses should only be used for instances of DpadRecyclerView and not other RecyclerViews.
an optional DpadSpacingLookup to filter layout positions that shouldn't have spacing applied
Checks if a decoration should be applied for a given RecyclerView.ViewHolder
true if the ViewHolder should have spacing applied to
the ViewHolder currently in layout
the item count at the layout stage. See RecyclerView.State.getItemCount
An item decoration that applies a spacing to all sides of a view part of a grid.
An item decoration that applies a spacing to all sides of a view part of a Column or Row layout.
A base RecyclerView.ItemDecoration that checks if spacing should be applied for a given position using DpadSpacingLookup.
Checks if a decoration should be applied for a given RecyclerView.ViewHolder
Holds the scroll state of nested DpadRecyclerView. Use it to save and restore the scroll state of all RecyclerViews in a single screen.
Call this when the ViewHolder is bound and after adapter contents are updated in RecyclerView.Adapter.onBindViewHolder.
Call this when the ViewHolder is recycled in RecyclerView.Adapter.onViewRecycled. This will clear the adapter by default to ensure that children are removed from the layout. To disable this, pass false in detachAdapter
Call this when the ViewHolder is bound and after adapter contents are updated in RecyclerView.Adapter.onBindViewHolder.
Ensure that adapter contains the dataset before calling this method
RecyclerView to be restored
unique identifier for recyclerView
adapter to be bound to this RecyclerView
Call this when the ViewHolder is recycled in RecyclerView.Adapter.onViewRecycled. This will clear the adapter by default to ensure that children are removed from the layout. To disable this, pass false in detachAdapter
RecyclerView to be saved
unique identifier for recyclerView
true to detach the RecyclerView.Adapter or false to skip that behavior. Default: true
DpadScrollState to save and restore scroll states of DpadRecyclerView
DpadViewHolderState to save and restore view states of ViewHolders part of a DpadRecyclerView
Saves and restores scroll states and ViewHolder states. Check DpadScrollState and DpadViewHolderState for more information.
This class is lifecycle-aware and will contribute to Activity.onSaveInstanceState or Fragment.onSaveInstanceState via SavedStateRegistryOwner, unless setSaveInstanceStateEnabled is used to disable this behavior.
Control whether state should be saved via Activity.onSaveInstanceState or Fragment.onSaveInstanceState, false otherwise. Default is true.
Control whether state should be saved via Activity.onSaveInstanceState or Fragment.onSaveInstanceState, false otherwise. Default is true.
true if state should be persisted, false otherwise.
Holds the view hierarchy state of some RecyclerView.ViewHolder. Use saveState to save a RecyclerView.ViewHolder and restoreState to restore its state.
Consider using this when you need to persist some View state (e.g text input) inside your ViewHolders.
ViewHolder to be restored
unique identifier for holder
true to prevent this state from being restored multiple times, or false to still keep it. Default: false
ViewHolder to be saved
unique identifier for holder
Holds the scroll state of nested DpadRecyclerView. Use it to save and restore the scroll state of all RecyclerViews in a single screen.
Saves and restores scroll states and ViewHolder states. Check DpadScrollState and DpadViewHolderState for more information.
Holds the view hierarchy state of some RecyclerView.ViewHolder. Use saveState to save a RecyclerView.ViewHolder and restoreState to restore its state.
When true, aligns to View.getBaseline for the view used for the alignment
The keyline position for the alignment. Default: 0.5f (center)
Set isFractionEnabled to false in case you want to disable this
Alignment configuration for aligning views in relation to its dimensions
the mutable collection of items backing the adapter
Indicates that the dragging action has started. DpadRecyclerView will receive focus
Indicates that the dragging action has stopped
Indicates that the dragging action has started. DpadRecyclerView will receive focus
the view holder that is being dragged
Indicates that the dragging action has stopped
Attaches the DpadRecyclerView that will be dragged. This is required before calling startDrag
Detaches the previously attached DpadRecyclerView and stops dragging
A helper class for re-ordering the contents of a DpadRecyclerView.
To use this, your adapter needs to implement DpadDragHelper.DragAdapter and expose the mutable collection via DpadDragHelper.DragAdapter.getMutableItems.
True if the attached DpadRecyclerView is currently in drag mode, false otherwise
Attaches the DpadRecyclerView that will be dragged. This is required before calling startDrag
Detaches the previously attached DpadRecyclerView and stops dragging
Cancels the current ongoing dragging action DragCallback.onDragStopped will be called after this method
True if the attached DpadRecyclerView is currently in drag mode, false otherwise
Starts the dragging action for the ViewHolder at position.
DragCallback.onDragStarted will be called after this method if this returns true
true if the dragging action was started, false otherwise
the position of the item to be dragged
Cancels the current ongoing dragging action DragCallback.onDragStopped will be called after this method
Mirrors both the min and max edge, so that infinite scroll is supported in both directions
Returns a representation of an immutable list of all enum entries, in the order they're declared.
This method may be used to iterate over the enum entries.
Defines how items are looped around in DpadRecyclerView.
Looping is only supported for single span layouts.
If the layout doesn't fill the entire viewport, then looping is disabled
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
Returns an array containing the constants of this enum type, in the order they're declared.
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
if this enum type has no constant with the specified name
Returns an array containing the constants of this enum type, in the order they're declared.
This method may be used to iterate over the constants.
Listener for intercepting key dispatch events.
true if the key dispatch event should be consumed.
Listener for receiving notifications of a completed layout pass by the LayoutManager of this RecyclerView
Called after a full layout calculation has finished.
Transient state of RecyclerView
Listener for intercepting generic motion dispatch events.
true if the motion event should be consumed.
Listener for intercepting touch dispatch events
true if event should be consumed
Listener for intercepting unhandled key events.
true if the key event should be consumed.
Defines duration in milliseconds of smoothScrollBy.
Duration in milliseconds or UNDEFINED_DURATION for default value.
x distance in pixels.
y distance in pixels.
Defines interpolator of smoothScrollBy.
Interpolator to be used or null for default interpolator.
x distance in pixels.
y distance in pixels.
Defines behavior of duration and interpolator for smoothScrollBy.
Defines duration in milliseconds of smoothScrollBy.
Defines interpolator of smoothScrollBy.
Registers a callback to be invoked when this RecyclerView completes a layout pass.
The listener to be invoked.
Registers a callback to be invoked when an item has been focused
The listener to be invoked.
Registers a callback to be invoked when an item has been selected
The listener to be invoked.
Clears all listeners added by addOnLayoutCompletedListener
Clears all existing listeners added by addOnViewFocusedListener
Clears all existing listeners added by addOnViewHolderSelectedListener
Enables fading out the max edge to transparent.
true if edge fading should be enabled for the right or bottom of the layout
Enables fading out the min edge to transparent.
true if edge fading should be enabled for the left or top of the layout
Similar to LinearLayoutManager.findFirstCompletelyVisibleItemPosition
The adapter position of the first fully visible item or RecyclerView.NO_POSITION if there aren't any fully visible items
Similar to LinearLayoutManager.findFirstVisibleItemPosition
The adapter position of the first visible item or RecyclerView.NO_POSITION if there aren't any visible items
Similar to LinearLayoutManager.findLastCompletelyVisibleItemPosition
The adapter position of the last fully visible item or RecyclerView.NO_POSITION if there aren't any fully visible items
Similar to LinearLayoutManager.findLastVisibleItemPosition
The adapter position of the last visible item or RecyclerView.NO_POSITION if there aren't any visible items
the current child alignment configuration
the number of available sub positions for the current selected item or 0 if there's none. See DpadViewHolder.getSubPositionAlignments
the current FocusableDirection. Default is FocusableDirection.STANDARD
number of items to prefetch
the listener set by setOnKeyInterceptListener
the listener set by setOnMotionInterceptListener
the listener set by setOnUnhandledKeyListener
the current parent alignment configuration
the current selected position or RecyclerView.NO_POSITION if there's none
the current selected sub position or 0 if there's none
See setSmoothScrollSpeedFactor.
Factor of how slow the smooth scroller runs. Default value is 1f.
See setSpanCount
A RecyclerView that scrolls to items on DPAD key events.
Items are aligned based on the following configurations:
ParentAlignment aligns items in relation to this RecyclerView's dimensions
ChildAlignment aligns items in relation to their View's dimensions
Individual sub position configurations returned by DpadViewHolder.getSubPositionAlignments
This DpadRecyclerView will only scroll automatically when it has focus and receives DPAD key events. To scroll manually to any given item, check setSelectedPosition, setSelectedPositionSmooth and other related methods.
When using wrap_content for the main scrolling direction, DpadRecyclerView will still measure itself to match its parent's size, but will layout all items at once without any recycling.
Listener for intercepting key dispatch events.
Listener for receiving notifications of a completed layout pass by the LayoutManager of this RecyclerView
Listener for intercepting generic motion dispatch events.
Listener for intercepting touch dispatch events
Listener for intercepting unhandled key events.
Defines behavior of duration and interpolator for smoothScrollBy.
Registers a callback to be invoked when this RecyclerView completes a layout pass.
Registers a callback to be invoked when an item has been focused
Registers a callback to be invoked when an item has been selected
Clears all listeners added by addOnLayoutCompletedListener
Clears all existing listeners added by addOnViewFocusedListener
Clears all existing listeners added by addOnViewHolderSelectedListener
Enables fading out the max edge to transparent.
Enables fading out the min edge to transparent.
See setSpanCount
See: setLayoutEnabled
Returns if views are laid out from the opposite direction of the layout.
See setScrollEnabled.
Removes a listener added by addOnLayoutCompletedListener
Removes a listener added by addOnViewFocusedListener
Removes a listener added by addOnViewHolderSelectedListener
Updates both parent and child alignments
Updates the child alignment configuration for child views of this RecyclerView
Sets the strategy for calculating extra layout space.
Changes how RecyclerView will find the next focusable view. Check FocusableDirection for all supported directions. Default is FocusableDirection.STANDARD
Enables or disables the default rule of drawing the selected view after all other views. Default is true
Sets whether focus can move out from the front and/or back of the RecyclerView.
Sets whether focus can move out from the opposite front and/or back of the RecyclerView
Disables or enables focus search.
Disables or enables focus search while RecyclerView is animating item changes. See RecyclerView.isAnimating.
Sets the gravity used for child view positioning. Defaults to Gravity.TOP for horizontal orientation and Gravity.START for vertical orientation.
Controls the return value of View.hasOverlappingRendering.
Sets the number of items to prefetch in RecyclerView.LayoutManager.collectInitialPrefetchPositions, which defines how many inner items should be prefetched when this RecyclerView is nested inside another RecyclerView.
Allows disabling the layout of children. All children are removed if layout is disabled
By default, DpadRecyclerView skips layout requests during scrolling because of:
Updates the loop direction used by this DpadRecyclerView. By default, the layout does not loop around the items
Sets the length of the fading effect applied to the max edge in pixels
Sets the length of the fading effect applied to the min edge in pixels
Sets the length of the fading effect applied to the min edge in pixels
Sets the start position of the fading effect applied to the min edge in pixels. Default is 0, which means that the fading effect starts from the min edge (left or top)
Registers a callback to be invoked when an item of this DpadRecyclerView has been laid out.
Set a listener that intercepts key events received in dispatchKeyEvent
Sets the generic motion intercept listener.
Sets a listener for intercepting touch events
Set a listener that intercepts unhandled key events from dispatchKeyEvent
Updates the orientation of the PivotLayoutManager used by this RecyclerView
Updates the parent alignment configuration for child views of this RecyclerView
Set whether the LayoutManager of this RecyclerView will recycle its children when this RecyclerView is detached from the window.
Used to reverse item traversal and layout order. This behaves similar to the layout change for RTL views. When set to true, first item is laid out at the end of the UI, second item is laid out before it etc.
Enables or disables scrolling. When this is disabled, DpadRecyclerView can still change focus on DPAD events unless setFocusSearchDisabled is also set.
Changes the selected item immediately without any scroll animation.
Performs a task on a ViewHolder at a given position after scrolling to it.
Changes the selected item and runs an animation to scroll to the target position.
Performs a task on a ViewHolder at a given position after scrolling to it.
Changes the sub selected view immediately without any scroll animation.
Changes the main selection and sub selected view immediately without any scroll animation.
Performs a task on a ViewHolder at a given position and sub position after scrolling to it.
Changes the sub selected view and runs and animation to scroll to it.
Performs a task on a ViewHolder at a given position and sub position after scrolling to it.
Enable or disable smooth scrolling to new focused position. By default, this is set to true. When set to false, RecyclerView will scroll immediately to the focused view without any animation.
Set a custom behavior for smoothScrollBy
Whenever the user triggers a focus change via a key event, DpadRecyclerView will check if it already has max number of pending alignment changes before dispatching focus to the next view.
When the user holds down a key, a lot of key events will be generated by the system. These events are generated a lot faster than this DpadRecyclerView can scroll, so these events need to be cached until the user stops pressing the key.
Set how slow the smooth scroller should run. Example:
Updates the number of spans of the PivotLayoutManager used by this RecyclerView.
Updates the DpadSpanSizeLookup used by the layout manager of this RecyclerView.
See setFocusDrawingOrderEnabled
true if the selected child view is drawn at last, false otherwise
True if focus search is disabled.
See RecyclerView.LayoutManager.isItemPrefetchEnabled
True if items should be prefetched in between traversals.
See: setLayoutEnabled
Returns if views are laid out from the opposite direction of the layout.
If layout is reversed or not.
true if edge fading is enabled for the right or bottom of the layout
true if edge fading is enabled for the left or top of the layout
See setScrollEnabled.
Removes a listener added by addOnLayoutCompletedListener
The listener to be removed.
Removes a listener added by addOnViewHolderSelectedListener
The listener to be removed.
Updates both parent and child alignments
the parent alignment configuration
the child alignment configuration
true if the alignment change should be animated
Updates the child alignment configuration for child views of this RecyclerView
the child alignment configuration
true if the alignment change should be animated
Sets the strategy for calculating extra layout space.
Note that this is not supported if DpadLoopDirection is used since that would potentially lead to duplicate items in the layout.
Check ExtraLayoutSpaceStrategy for more information.
Enables or disables the default rule of drawing the selected view after all other views. Default is true
True to draw the selected child at last, false otherwise.
Sets whether focus can move out from the front and/or back of the RecyclerView.
For the vertical orientation, this controls whether focus can move out from the top. For the horizontal orientation, this controls whether focus can move out the left or right (in RTL) side of the grid.
For the vertical orientation, this controls whether focus can move out from the bottom. For the horizontal orientation, this controls whether focus can move out the right or left (in RTL) side of the grid.
Sets whether focus can move out from the opposite front and/or back of the RecyclerView
For the vertical orientation, this controls whether focus can move out from the left of the grid. For the horizontal orientation, this controls whether focus can move out the top side of the grid.
For the vertical orientation, this controls whether focus can move out from the right of the grid. For the horizontal orientation, this controls whether focus can move out the bottom side of the grid.
Disables or enables focus search.
True to disable focus search, false to enable.
Disables or enables focus search while RecyclerView is animating item changes. See RecyclerView.isAnimating.
This is disabled by default.
True to enable focus search while RecyclerView is animating item changes, or false to disable
Changes how RecyclerView will find the next focusable view. Check FocusableDirection for all supported directions. Default is FocusableDirection.STANDARD
Sets the gravity used for child view positioning. Defaults to Gravity.TOP for horizontal orientation and Gravity.START for vertical orientation.
This is only supported for single rows (i.e 1 span)
See Gravity
Controls the return value of View.hasOverlappingRendering.
true if overlapping rendering is enabled. Default is true
Sets the number of items to prefetch in RecyclerView.LayoutManager.collectInitialPrefetchPositions, which defines how many inner items should be prefetched when this RecyclerView is nested inside another RecyclerView.
Number of items to prefetch
See RecyclerView.LayoutManager.setItemPrefetchEnabled
True if items should be prefetched in between traversals.
Allows disabling the layout of children. All children are removed if layout is disabled
true to enable layout, false otherwise.
By default, DpadRecyclerView skips layout requests during scrolling because of:
Compose animations trigger a full unnecessary layout-pass
Content jumping around while scrolling is not ideal sometimes
true if layout requests should be possible while scrolling, or false if they should be postponed until RecyclerView.SCROLL_STATE_IDLE. Default is false.
Updates the loop direction used by this DpadRecyclerView. By default, the layout does not loop around the items
the DpadLoopDirection to use for looping items
Sets the length of the fading effect applied to the max edge in pixels
Sets the length of the fading effect applied to the min edge in pixels
Sets the length of the fading effect applied to the min edge in pixels
Sets the start position of the fading effect applied to the min edge in pixels. Default is 0, which means that the fading effect starts from the min edge (left or top)
Registers a callback to be invoked when an item of this DpadRecyclerView has been laid out.
the listener to be invoked.
Set a listener that intercepts key events received in dispatchKeyEvent
The key intercept listener.
Sets the generic motion intercept listener.
The motion intercept listener.
Sets a listener for intercepting touch events
the touch intercept listener
Set a listener that intercepts unhandled key events from dispatchKeyEvent
The unhandled key intercept listener.
Updates the orientation of the PivotLayoutManager used by this RecyclerView
either RecyclerView.VERTICAL or RecyclerView.HORIZONTAL
Updates the parent alignment configuration for child views of this RecyclerView
the parent alignment configuration
true if the alignment change should be animated
Set whether the LayoutManager of this RecyclerView will recycle its children when this RecyclerView is detached from the window.
If you are re-using a RecyclerView.RecycledViewPool, it might be a good idea to set this flag to true so that views will be available to other RecyclerViews immediately.
Whether children should be recycled in detach or not.
Used to reverse item traversal and layout order. This behaves similar to the layout change for RTL views. When set to true, first item is laid out at the end of the UI, second item is laid out before it etc.
For horizontal layouts, it depends on the layout direction.
When set to true:
If this DpadRecyclerView is LTR, then it will layout from RTL.
If it is RTL, it will layout from LTR.
True to reverse the layout order
Enables or disables scrolling. When this is disabled, DpadRecyclerView can still change focus on DPAD events unless setFocusSearchDisabled is also set.
true if scrolling should be enabled, false otherwise
Changes the selected item and runs an animation to scroll to the target position.
Adapter position of the item to select
Performs a task on a ViewHolder at a given position after scrolling to it.
Adapter position of the item to select
Task to executed on the ViewHolder at the given position
Changes the selected item immediately without any scroll animation.
adapter position of the item to select
Performs a task on a ViewHolder at a given position after scrolling to it.
Adapter position of the item to select
Task to executed on the ViewHolder at the given position
Changes the sub selected view and runs and animation to scroll to it.
index of the alignment from DpadViewHolder.getSubPositionAlignments
Changes the sub selected view and runs and animation to scroll to it.
Adapter position of the item to select
index of the alignment from DpadViewHolder.getSubPositionAlignments
Performs a task on a ViewHolder at a given position and sub position after scrolling to it.
Adapter position of the item to select
index of the alignment from DpadViewHolder.getSubPositionAlignments
Task to executed on the ViewHolder at the given position
Changes the main selection and sub selected view immediately without any scroll animation.
Adapter position of the item to select
index of the alignment from DpadViewHolder.getSubPositionAlignments
Performs a task on a ViewHolder at a given position and sub position after scrolling to it.
Adapter position of the item to select
index of the alignment from DpadViewHolder.getSubPositionAlignments
Task to executed on the ViewHolder at the given position
Changes the sub selected view immediately without any scroll animation.
index of the alignment from DpadViewHolder.getSubPositionAlignments
Enable or disable smooth scrolling to new focused position. By default, this is set to true. When set to false, RecyclerView will scroll immediately to the focused view without any animation.
true to smooth scroll to the new focused position, false to scroll immediately
Set a custom behavior for smoothScrollBy
Custom behavior or null for the default behavior.
Whenever the user triggers a focus change via a key event, DpadRecyclerView will check if it already has max number of pending alignment changes before dispatching focus to the next view.
Example: User presses KeyEvent.KEYCODE_DPAD_RIGHT 5 times and max is 2.
If focus is at position N, pressing KeyEvent.KEYCODE_DPAD_RIGHT 5 times will only dispatch focus up to position N + max instead of N + 5
Once a view is aligned to its final position or RecyclerView.getScrollState is RecyclerView.SCROLL_STATE_IDLE, we consume that alignment change.
Maximum number of pending alignment changes
When the user holds down a key, a lot of key events will be generated by the system. These events are generated a lot faster than this DpadRecyclerView can scroll, so these events need to be cached until the user stops pressing the key.
If this value is too high, then scrolling will take place a lot longer after the key press stops. And if this value is too low, DpadRecyclerView might miss many key events.
The default value is 10.
It might make sense to decrease this if setSmoothScrollSpeedFactor was increased to avoid scrolling for too long after key presses are over.
Maximum number of pending key events to be remembered.
Set how slow the smooth scroller should run. Example:
When set to 2f, the smooth scroller is twice slower.
When set to 0.5f, the smooth scroller is twice faster.
The value is 1f by default.
Factor of how slow the smooth scroll is.
Updates the number of spans of the PivotLayoutManager used by this RecyclerView.
number of columns in vertical orientation, or number of rows in horizontal orientation. Must be greater than 0
Updates the DpadSpanSizeLookup used by the layout manager of this RecyclerView.
the new span size configuration
the number of pixels we should scroll for this event
Attaches this DpadScroller to a new DpadRecyclerView to start observing key events. If you no longer need this behavior, call detach
The RecyclerView that will be scrolled discretely
Stops observing key events to scroll the current attached DpadRecyclerView, if any exists
A helper class that allows scrolling a DpadRecyclerView based on specific scroll distances, ignoring the default alignment behavior.
A typical use case for this class is a terms & conditions page, where a large amount of text is displayed, which the user isn't expected to interact with
Attaches this DpadScroller to a new DpadRecyclerView to start observing key events. If you no longer need this behavior, call detach
Stops observing key events to scroll the current attached DpadRecyclerView, if any exists
Enables or disables smooth scrolling on key events
Enables or disables smooth scrolling on key events
A SnapHelper that scrolls Views to their alignment configuration and performs selections automatically. Use this only if you need to support touch event handling, as DpadRecyclerView by default does not handle selection on touch events.
Returns the number of span occupied by the item at position.
The number of spans occupied by the item at the provided position
The adapter position of the item
A helper class to provide the number of spans each item occupies.
Default implementation sets each item to occupy exactly 1 span.
Extracted from: GridLayoutManager.SpanSizeLookup to access package protected methods
Returns the number of span occupied by the item at position.
the alignment configurations to use for this ViewHolder, or empty if it should be aligned using the configuration of the DpadRecyclerView
A ViewHolder managed by DpadRecyclerView.
Implement this in case you're interested in receiving selection changes or customising alignment
For receiving focus changes, use the standard View.setOnFocusChangeListener instead
Will be called whenever this ViewHolder is no longer the current one selected.
Will be called whenever this ViewHolder is the current one selected.
Will be called after onViewHolderSelected once the RecyclerView stops scrolling and the ViewHolder is aligned in its final position
Will be called whenever this ViewHolder is no longer the current one selected.
This is NOT the same as losing focus.
To observe focus changes, you need to use the focus listener set via View.setOnFocusChangeListener
This is called automatically by DpadRecyclerView on selection changes.
Will be called after onViewHolderSelected once the RecyclerView stops scrolling and the ViewHolder is aligned in its final position
Will be called whenever this ViewHolder is the current one selected.
This is NOT the same as gaining focus.
To observe focus changes, you need to use the focus listener set via View.setOnFocusChangeListener
This is called automatically by DpadRecyclerView on selection changes.
Calculates the extra space that should be laid out (in pixels)
By default, DpadRecyclerView will not layout any extra space to minimise the number of views in memory.
the extra space (in pixels) to be added to the end of the layout
the current DpadRecyclerView state
the extra space (in pixels) to be added to the start of the layout
the current DpadRecyclerView state
Overrides the default mechanism for laying out extra views at the borders of the RecyclerView. Check LinearLayoutManager.calculateExtraLayoutSpace for more details.
By default, DpadRecyclerView will not layout any extra space to minimise the number of views in memory.
Similar to STANDARD, but applies a different logic at the edges:
If focusing forward (e.g Dpad right on a vertical grid) on the last column, the next focused item will be the item in the first column of the next row.
If focusing backwards (e.g Dpad left on a vertical grid) on the first column, the next focused item will be the item in the last column of the previous row.
Returns a representation of an immutable list of all enum entries, in the order they're declared.
This method may be used to iterate over the enum entries.
Similar to STANDARD, but applies a different logic at the edges:
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
Returns an array containing the constants of this enum type, in the order they're declared.
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
if this enum type has no constant with the specified name
Returns an array containing the constants of this enum type, in the order they're declared.
This method may be used to iterate over the constants.
Listener for receiving layout events of children of this RecyclerView
Called after a ViewHolder's view has been added to the view hierarchy and has been laid out
the RecyclerView that contains this child
the RecyclerView.ViewHolder that was laid out
Callback for receiving a notification when a View of a RecyclerView.ViewHolder has been focused.
Be aware that a RecyclerView.ViewHolder selection can change without focus and, in that case, this callback is not invoked. Instead, use OnViewHolderSelectedListener for observing selections
The RecyclerView.ViewHolder within the RecyclerView that is focused
The actual child View that received focus. Can be a child of a nested RecyclerView.
Callback for receiving a notification when a ViewHolder has been selected. There are two methods:
onViewHolderSelected is called when the ViewHolder has been selected
onViewHolderSelectedAndAligned is called when the ViewHolder has been selected and aligned out to its final position
Called when child has scrolled to its final position
Called when child has scrolled to its final position
The RecyclerView where the selection happened.
The ViewHolder within the RecyclerView that is selected, or null if no view is selected.
The position of the view in the adapter, or NO_POSITION if no view is selected.
The index of the alignment from DpadViewHolder.getSubPositionAlignments, or 0 if there is no custom alignment
The RecyclerView where the selection happened.
The ViewHolder within the RecyclerView that is selected, or null if no view is selected.
The position of the view in the adapter, or NO_POSITION if no view is selected.
The index of the alignment from DpadViewHolder.getSubPositionAlignments, or 0 if there is no custom alignment
All items will be always aligned to the keyline position except the item at the end. This will be the bottom for Vertical orientation, or end for Horizontal orientation
All items will be always aligned to the keyline position except the item at the start. This will be the top for Vertical orientation, or start for the horizontal orientation
All items will be always aligned to the keyline position except the items at the start and end edges
Returns a representation of an immutable list of all enum entries, in the order they're declared.
This method may be used to iterate over the enum entries.
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
Returns an array containing the constants of this enum type, in the order they're declared.
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
if this enum type has no constant with the specified name
Returns an array containing the constants of this enum type, in the order they're declared.
This method may be used to iterate over the constants.
The specific alignment to a given edge that overrides the keyline alignment. See Edge Default: Edge.MIN_MAX
The keyline position for the alignment. Default: 0.5f (center)
Set isFractionEnabled to false in case you want to disable this
Alignment configuration for aligning views in relation to the RecyclerView bounds
The specific alignment to a given edge that overrides the keyline alignment. See Edge Default: Edge.MIN_MAX
true if fraction should be used to position the item.
When Edge.MAX or Edge.MIN are used, this flag decides if the Views should be aligned to the keyline when there are few items, overriding the edge preference.
Default is: True for Edge.MAX, which means we prefer aligning to the keyline False for Edge.MIN, which means we prefer aligning to the min edge.
When true, aligns to View.getBaseline for the view used for the alignment
The id of the child view that should be used for the alignment. If it is View.NO_ID, then the root view will be used instead. This is not necessarily the same view that will receive focus.
The keyline position for the alignment. Default: 0.5f (center)
Set isFractionEnabled to false in case you want to disable this
Alignment configuration specific to a certain sub position.
This will override the default alignment set from ChildAlignment.
The id of the child view that should be used for the alignment. If it is View.NO_ID, then the root view will be used instead. This is not necessarily the same view that will receive focus.
When true, aligns to View.getBaseline for the view used for the alignment
A RecyclerView.RecycledViewPool that does not limit the number of ViewHolders recycled.
This is meant to be shared across different RecyclerView to minimise ViewHolder inflation time and memory consumption, since RecyclerView will only create and bind the absolute minimum number of ViewHolders it really needs.
See fraction
See offset
When true, aligns to View.getBaseline for the view used for the alignment
The keyline position for the alignment. Default: 0.5f (center)
Set isFractionEnabled to false in case you want to disable this
When true, aligns to View.getBaseline for the view used for the alignment
if this task should only be executed when a ViewHolder is aligned to its final position, or false if it should be executed immediately after the selection
if this task should only be executed when a ViewHolder is aligned to its final position, or false if it should be executed immediately after the selection
Task that's scheduled and executed when a ViewHolder is selected
if this task should only be executed when a ViewHolder is aligned to its final position, or false if it should be executed immediately after the selection
Alignment configuration for aligning views in relation to its dimensions
A helper class for re-ordering the contents of a DpadRecyclerView.
Defines how items are looped around in DpadRecyclerView.
A RecyclerView that scrolls to items on DPAD key events.
A helper class that allows scrolling a DpadRecyclerView based on specific scroll distances, ignoring the default alignment behavior.
A SnapHelper that scrolls Views to their alignment configuration and performs selections automatically. Use this only if you need to support touch event handling, as DpadRecyclerView by default does not handle selection on touch events.
A helper class to provide the number of spans each item occupies.
A ViewHolder managed by DpadRecyclerView.
Overrides the default mechanism for laying out extra views at the borders of the RecyclerView. Check LinearLayoutManager.calculateExtraLayoutSpace for more details.
Listener for receiving layout events of children of this RecyclerView
Callback for receiving a notification when a View of a RecyclerView.ViewHolder has been focused.
Callback for receiving a notification when a ViewHolder has been selected. There are two methods:
Alignment configuration for aligning views in relation to the RecyclerView bounds
Alignment configuration specific to a certain sub position.
A RecyclerView.RecycledViewPool that does not limit the number of ViewHolders recycled.
Task that's scheduled and executed when a ViewHolder is selected
2024-06-17
+1.7.0-beta03DpadDragHelper for drag and drop support (#216). Documentation available here.recyclerView.setFocusableDirection(FocusableDirection.CIRCULAR) can also be used in linear layouts that don't fill the entire space. (#225focusOutFront and focusOutBack are enabled by default due to feedback from library users (#223)2024-06-04
+DpadSelectionSnapHelper to improve selection on touch events. (#215)isFocusable to DpadComposeFocusViewHolder to allow disabling focus for some items. DpadSpanSizeLookup. (#217)DpadSpanSizeLookup. (#218)2024-05-31
+DpadStateRegistry that assists in saving and restoring the scroll state or view state of ViewHolders (#45)setLayoutWhileScrollingEnabled(true)DpadRecyclerView losing focus in some cases when adapter contents are updated during scroll events. (#206)2024-03-23
+2024-03-17
+DpadComposeFocusViewHolder that allows sending the focus state down to Composables (#193)Modifier.dpadClickable for playing the click sound after clicking on a Composable. Fix for: (/b/268268856)setLayoutWhileScrollingEnabled(false) (#196)addOnViewFocusedListener to observe focus changes independently from selection changes. (#197)DpadAbstractComposeViewHolder is now removed. Replace it with either DpadComposeFocusViewHolder or DpadComposeViewHolder.2024-03-13
+RecyclerViewCompositionStrategy.DisposeOnRecycled for compose interop
+ to re-use compositions when views are detached and attached from the window again.setSelectedSubPosition that allows passing a callback for the target alignment (#43)DpadScroller for scrolling without any alignment. Typical use case is for long text displays (terms & conditions and consent pages).2024-02-03
+2024-01-28
+RecyclerViewCompositionStrategy.DisposeOnRecycled for compose interop
+to re-use compositions when views are detached and attached from the window again.setRecycleChildrenOnDetach is used.2024-01-17
+setSelectedSubPosition that allows passing a callback for the target alignment (#43)2024-01-10
+2023-12-27
+2023-11-25
+DpadScroller for scrolling without any alignment. Typical use case is for long text displays (terms & conditions and consent pages).2023-11-12
+2023-10-18
+androidx.recyclerview to version 1.3.2 to fix sporadic crashes during animations: (/9e69afd)androidx.collection to stable version 1.3.02023-09-15
+app:spanCount attribute is used for grids (#162)2023-09-10
+Edge.MAX alignment is used: (#160)app:dpadRecyclerViewParentAlignmentPreferKeylineOverEdge not being applied correctly2023-08-04
+2023-06-23
+2023-06-08
+2023-05-16
+app:dpadRecyclerViewParentAlignmentPreferKeylineOverEdge (#145)2023-05-07
+2023-05-03
+1.4.2getSpanSizeLookup() to DpadRecyclerViewonViewHolderSelectedAndAligned to DpadViewHolderDpadAbstractComposeViewHolder to allow subclasses to get access to focus changes. Check Compose interoperability for more information.See the documentation here
+KeyEvents.back() to easily press back key eventsDpadRecyclerViewActions.scrollTo and DpadRecyclerViewActions.scrollToHolder to scroll to specific ViewHolders using KeyEvents.DpadViewAssertions for asserting focus states:DpadViewAssertions.hasFocus()DpadViewAssertions.doesNotHaveFocus()DpadViewAssertions.isFocused()DpadViewAssertions.isNotFocused()2023-04-18
+1.3.0DpadRecyclerView not measuring itself correctly when wrap_content is used. (#123)2023-04-02
+2023-02-21
+dpadrecyclerview-compose module that contains DpadComposeViewHolder for Compose interoperability. Check Compose interoperability for more information.setSmoothScrollMaxPendingMoves(0) to fully prevent unwanted scroll events.offsetRatio in ParentAlignment, ChildAlignment and SubPositionAlignment was renamed to fraction.Edge.MIN is used and there's a small number of adapter items (#93)DpadRecyclerView scrolling automatically to the current selected position when there's a touch event (#104)KeyEvents.click() to easily dispatch click events in UI tests2023-02-13
+DpadLinearSpacingItemDecoration and DpadGridSpacingItemDecoration to easily set spacing between itemssetScrollEnabled to enable or disable scroll eventssetLayoutEnabled to enable or disable the layout of childrensetReverseLayoutsetSmoothScrollMaxPendingAlignments allows limiting the number of scroll changes still not appliedsetSmoothScrollMaxPendingMoves allows remembering DPAD events not yet appliedsetOnChildLaidOutListener to observe when each view is laid outsetFocusSearchEnabledDuringAnimations allows enabling or disabling focus changes during item animations.ViewHolderAlignment was renamed to SubPositionAlignment. Now DpadViewHolder returns these alignments in getSubPositionAlignments.DpadRecyclerView not searching for focus if it's currently retaining focus due to a pivot removal. This prevented accumulating pending moves during smooth scrolling.DpadRecyclerView now won't search for focus if its parent RecyclerView is still smooth scrolling (#50)ItemAnimator animations were running when scrolling during item changes (#47)DisableIdleTimeoutRule will now wait for idle input after the test is over to avoid dispatching key events to other tests2023-01-26
+DpadLayoutManager with new PivotLayoutManager for proper customization of layout logic (#10), (#16)2022-12-10
+DpadRecyclerViewRecyclerView.canScrollHorizontally and RecyclerView.canScrollVertically since they're not used and clients can create them themselves2022-11-06
+