com.github.rubensousa.gravitysnaphelper

Class GravitySnapHelper

java.lang.Object

androidx.recyclerview.widget.RecyclerView.OnFlingListener

androidx.recyclerview.widget.SnapHelper

androidx.recyclerview.widget.LinearSnapHelper

com.github.rubensousa.gravitysnaphelper.GravitySnapHelper

Direct Known Subclasses:

GravityPagerSnapHelper

public class GravitySnapHelper
extends androidx.recyclerview.widget.LinearSnapHelper

A LinearSnapHelper that allows snapping to an edge or to the center.

Possible snap positions: Gravity.START, Gravity.TOP, Gravity.END, Gravity.BOTTOM, Gravity.CENTER.

To customize the scroll duration, use setScrollMsPerInch(float).

To customize the maximum scroll distance during flings, use setMaxFlingSizeFraction(float) or setMaxFlingDistance(int)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	GravitySnapHelper.SnapListener A listener that's called when the RecyclerView used by GravitySnapHelper changes its scroll state to RecyclerView.SCROLL_STATE_IDLE and there's a valid snap position.

Field Summary

Fields

Modifier and Type	Field and Description
static int	FLING_DISTANCE_DISABLE
static float	FLING_SIZE_FRACTION_DISABLE

Constructor Summary

Constructors

Constructor and Description
GravitySnapHelper(int gravity)
GravitySnapHelper(int gravity, boolean enableSnapLastItem)
GravitySnapHelper(int gravity, boolean enableSnapLastItem, GravitySnapHelper.SnapListener snapListener)
GravitySnapHelper(int gravity, GravitySnapHelper.SnapListener snapListener)

Method Summary

Modifier and Type	Method and Description
void	attachToRecyclerView(androidx.recyclerview.widget.RecyclerView recyclerView)
int[]	calculateDistanceToFinalSnap(androidx.recyclerview.widget.RecyclerView.LayoutManager layoutManager, android.view.View targetView)
int[]	calculateScrollDistance(int velocityX, int velocityY)
androidx.recyclerview.widget.RecyclerView.SmoothScroller	createScroller(androidx.recyclerview.widget.RecyclerView.LayoutManager layoutManager)
android.view.View	findSnapView(androidx.recyclerview.widget.RecyclerView.LayoutManager lm)
android.view.View	findSnapView(androidx.recyclerview.widget.RecyclerView.LayoutManager lm, boolean checkEdgeOfList)
int	getCurrentSnappedPosition()
int	getGravity() Get the current gravity being applied
int	getMaxFlingDistance()
float	getMaxFlingSizeFraction()
float	getScrollMsPerInch()
boolean	getSnapLastItem()
boolean	getSnapToPadding()
boolean	scrollToPosition(int position) This method will only work if there's a ViewHolder for the given position.
void	setGravity(int newGravity) Changes the gravity of this GravitySnapHelper and dispatches a smooth scroll for the new snap position.
void	setGravity(int newGravity, java.lang.Boolean smooth) Changes the gravity of this GravitySnapHelper and dispatches a smooth scroll for the new snap position.
void	setMaxFlingDistance(int distance) Changes the max fling distance in absolute values.
void	setMaxFlingSizeFraction(float fraction) Changes the max fling distance depending on the available size of the RecyclerView.
void	setScrollMsPerInch(float ms) Sets the scroll duration in ms per inch.
void	setSnapLastItem(boolean snap) Enable snapping of the last item that's snappable.
void	setSnapListener(GravitySnapHelper.SnapListener listener) Sets a GravitySnapHelper.SnapListener to listen for snap events
void	setSnapToPadding(boolean snapToPadding) If true, GravitySnapHelper will snap to the gravity edge plus any amount of padding that was set in the RecyclerView.
boolean	smoothScrollToPosition(int position) Unlike scrollToPosition(int), this method will generally always find a snap view if the position is valid.
void	updateSnap(java.lang.Boolean smooth, java.lang.Boolean checkEdgeOfList) Updates the current view to be snapped

Methods inherited from class androidx.recyclerview.widget.LinearSnapHelper

findTargetSnapPosition

Methods inherited from class androidx.recyclerview.widget.SnapHelper

createSnapScroller, onFling

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FLING_DISTANCE_DISABLE

public static final int FLING_DISTANCE_DISABLE

See Also:

Constant Field Values

FLING_SIZE_FRACTION_DISABLE

public static final float FLING_SIZE_FRACTION_DISABLE

See Also:

Constant Field Values

Constructor Detail

GravitySnapHelper

public GravitySnapHelper(int gravity)

GravitySnapHelper

public GravitySnapHelper(int gravity,
                         @NonNull
                         GravitySnapHelper.SnapListener snapListener)

GravitySnapHelper

public GravitySnapHelper(int gravity,
                         boolean enableSnapLastItem)

GravitySnapHelper

public GravitySnapHelper(int gravity,
                         boolean enableSnapLastItem,
                         @Nullable
                         GravitySnapHelper.SnapListener snapListener)

Method Detail

attachToRecyclerView

public void attachToRecyclerView(@Nullable
                                 androidx.recyclerview.widget.RecyclerView recyclerView)
                          throws java.lang.IllegalStateException

Overrides:

attachToRecyclerView in class androidx.recyclerview.widget.SnapHelper

Throws:

java.lang.IllegalStateException

findSnapView

@Nullable
public android.view.View findSnapView(@NonNull
                                                 androidx.recyclerview.widget.RecyclerView.LayoutManager lm)

Overrides:

findSnapView in class androidx.recyclerview.widget.LinearSnapHelper

findSnapView

@Nullable
public android.view.View findSnapView(@NonNull
                                                 androidx.recyclerview.widget.RecyclerView.LayoutManager lm,
                                                 boolean checkEdgeOfList)

calculateDistanceToFinalSnap

@NonNull
public int[] calculateDistanceToFinalSnap(@NonNull
                                                    androidx.recyclerview.widget.RecyclerView.LayoutManager layoutManager,
                                                    @NonNull
                                                    android.view.View targetView)

Overrides:

calculateDistanceToFinalSnap in class androidx.recyclerview.widget.LinearSnapHelper

calculateScrollDistance

@NonNull
public int[] calculateScrollDistance(int velocityX,
                                               int velocityY)

Overrides:

calculateScrollDistance in class androidx.recyclerview.widget.SnapHelper

createScroller

@Nullable
public androidx.recyclerview.widget.RecyclerView.SmoothScroller createScroller(androidx.recyclerview.widget.RecyclerView.LayoutManager layoutManager)

Overrides:

createScroller in class androidx.recyclerview.widget.SnapHelper

setSnapListener

public void setSnapListener(@Nullable
                            GravitySnapHelper.SnapListener listener)

Sets a GravitySnapHelper.SnapListener to listen for snap events

Parameters:

listener - a GravitySnapHelper.SnapListener that'll receive snap events or null to clear it

setGravity

public void setGravity(int newGravity,
                       java.lang.Boolean smooth)

Changes the gravity of this GravitySnapHelper and dispatches a smooth scroll for the new snap position.

Parameters:

newGravity - one of the following: Gravity.START, Gravity.TOP, Gravity.END, Gravity.BOTTOM, Gravity.CENTER

smooth - true if we should smooth scroll to new edge, false otherwise

updateSnap

public void updateSnap(java.lang.Boolean smooth,
                       java.lang.Boolean checkEdgeOfList)

Updates the current view to be snapped

Parameters:

smooth - true if we should smooth scroll, false otherwise

checkEdgeOfList - true if we should check if we're at an edge of the list and snap according to getSnapLastItem(), or false to force snapping to the nearest view

scrollToPosition

public boolean scrollToPosition(int position)

This method will only work if there's a ViewHolder for the given position.

Returns:

true if scroll was successful, false otherwise

smoothScrollToPosition

public boolean smoothScrollToPosition(int position)

Unlike scrollToPosition(int), this method will generally always find a snap view if the position is valid.

The smooth scroller from createScroller(RecyclerView.LayoutManager) will be used, and so will scrollMsPerInch for the scroll velocity

Returns:

true if scroll was successful, false otherwise

getGravity

public int getGravity()

Get the current gravity being applied

Returns:

one of the following: Gravity.START, Gravity.TOP, Gravity.END, Gravity.BOTTOM, Gravity.CENTER

setGravity

public void setGravity(int newGravity)

Changes the gravity of this GravitySnapHelper and dispatches a smooth scroll for the new snap position.

Parameters:

newGravity - one of the following: Gravity.START, Gravity.TOP, Gravity.END, Gravity.BOTTOM, Gravity.CENTER

getSnapLastItem

public boolean getSnapLastItem()

Returns:

true if this SnapHelper should snap to the last item

setSnapLastItem

public void setSnapLastItem(boolean snap)

Enable snapping of the last item that's snappable. The default value is false, because you can't see the last item completely if this is enabled.

Parameters:

snap - true if you want to enable snapping of the last snappable item

getMaxFlingDistance

public int getMaxFlingDistance()

Returns:

last distance set through setMaxFlingDistance(int) or FLING_DISTANCE_DISABLE if we're not limiting the fling distance

setMaxFlingDistance

public void setMaxFlingDistance(@Px
                                int distance)

Changes the max fling distance in absolute values.

Parameters:

distance - max fling distance in pixels or FLING_DISTANCE_DISABLE to disable fling limits

getMaxFlingSizeFraction

public float getMaxFlingSizeFraction()

Returns:

last distance set through setMaxFlingSizeFraction(float) or FLING_SIZE_FRACTION_DISABLE if we're not limiting the fling distance

setMaxFlingSizeFraction

public void setMaxFlingSizeFraction(float fraction)

Changes the max fling distance depending on the available size of the RecyclerView.

Example: if you pass 0.5f and the RecyclerView measures 600dp, the max fling distance will be 300dp.

Parameters:

fraction - size fraction to be used for the max fling distance or FLING_SIZE_FRACTION_DISABLE to disable fling limits

getScrollMsPerInch

public float getScrollMsPerInch()

Returns:

last scroll speed set through setScrollMsPerInch(float) or 100f

setScrollMsPerInch

public void setScrollMsPerInch(float ms)

Sets the scroll duration in ms per inch.

Default value is 100.0f

This value will be used in createScroller(RecyclerView.LayoutManager)

Parameters:

ms - scroll duration in ms per inch

getSnapToPadding

public boolean getSnapToPadding()

Returns:

true if this SnapHelper should snap to the padding. Defaults to false.

setSnapToPadding

public void setSnapToPadding(boolean snapToPadding)

If true, GravitySnapHelper will snap to the gravity edge plus any amount of padding that was set in the RecyclerView.

The default value is false.

Parameters:

snapToPadding - true if you want to snap to the padding

getCurrentSnappedPosition

public int getCurrentSnappedPosition()

Returns:

the position of the current view that's snapped or RecyclerView.NO_POSITION in case there's none.