### CHANGELOG

# Changelog

## 2.3.0

- Updated minSdk to 21
- Updated RecyclerView to 1.4.0
- Deleted deprecated `GravityPagerSnapHelper`. Use the following to replicate the behavior:

```kotlin
gravitySnapHelper.apply {
    setMaxFlingSizeFraction(1.0f)
    setScrollMsPerInch(50f) 
}
```

## 2.2.2

- Fixed IllegalArgumentException being incorrectly thrown in `GravitySnapRecyclerView` when Gravity.CENTER is used.

## 2.2.1

- Fixed `GravitySnapHelper` not dispatching snap events for edge items sometimes on `SnapListener`

## 2.2.0

### New features
- Added Gravity.CENTER support ([#21](https://github.com/rubensousa/GravitySnapHelper/issue/21))
- Added setMaxFlingDistance and setMaxFlingSizeFraction to change the max fling distance allowed ([#29](https://github.com/rubensousa/GravitySnapHelper/issue/29))
- Added setSnapToPadding to allow snapping to the padding set in the RecyclerView. Defaults to false ([#58](https://github.com/rubensousa/GravitySnapHelper/issue/58))
- Added GravitySnapRecyclerView that uses GravitySnapHelper by default
- Added setGravity to change the gravity of GravitySnapHelper
- Added setScrollMsPerInch to change the scroll speed
- Added setSnapListener to allow changing the SnapListener that was set or clearing it
- GravityPagerSnapHelper is now deprecated. Use GravitySnapHelper together with setMaxFlingSizeFraction() to achieve the same behavior
- Added updateSnap to update the snap position if for some reason snapping was stopped

### Improvements

- Improved behavior when smoothScrollToPosition is called. Now the smooth scroller is used
- Added getters to all relevant properties
- getCurrentSnappedPosition now searches for the correct snap view instead of returning the last position that we snapped to
- Added missing NonNull and Nullable annotations

## 2.1.0

- OrientationAwareRecyclerView now doesn't depend on LinearLayoutManager directly
- Fixed SnapListener not being called for the first position sometimes (#57)
- Added getCurrentSnappedPosition to GravitySnapHelper and GravityPagerSnapHelper

## 2.0

### New features:
- Migrated to AndroidX.
- Added smoothScrollToPosition and scrollToPosition methods that'll snap to a certain position.
- Added OrientationAwareRecyclerView that only handles scroll events according to its orientation.

### Bug fixes:
- Fixed snapping not working correctly for RecyclerViews with padding (#49)
- Fixed snapping not considering GridLayoutManager.SpanSizeLookup (#52)

## 1.5

- Fixed reverse layout causing scrolling issues (#40)

## 1.4

- Added Nullable and NonNull annotations
- Updated support library

## 1.3

- Fixed IllegalStateException being thrown when SnapHelper is attached twice to a RecyclerView (#23)
- Bumped min sdk to 14

## 1.2

- Added support for GridLayoutManager

## 1.1

- Added GravityPagerSnapHelper
- Updated support library

## 1.0

- GravitySnapHelper extends from LinearSnapHelper again
- Added SnapListener to listen for snap events


## 0.3

- Extend from SnapHelper until https://code.google.com/p/android/issues/detail?id=223649 gets fixed.

## 0.2

- Added RTL support
- Fixed GravitySnapHelper scrolling too far sometimes (#2)
- Added support to snap last items via enableLastItemSnap(boolean enable)


## 0.1

- Initial release

---

### README

# GravitySnapHelper

A SnapHelper that snaps a RecyclerView to an edge.

## Setup

```kotlin
implementation("com.github.rubensousa:gravitysnaphelper:2.3.0")
```

## How to use

You can either create a GravitySnapHelper, or use GravitySnapRecyclerView.

If you want to use GravitySnapHelper directly, 
you just need to create it and attach it to your RecyclerView:

```kotlin
val snapHelper = GravitySnapHelper(Gravity.START)
snapHelper.attachToRecyclerView(recyclerView)
```

If you want to use GravitySnapRecyclerView, you can use the following xml attributes for customisation:

```xml
<attr name="snapGravity" format="enum">
<attr name="snapEnabled" format="boolean" />
<attr name="snapLastItem" format="boolean" />
<attr name="snapToPadding" format="boolean" />
<attr name="snapScrollMsPerInch" format="float" />
<attr name="snapMaxFlingSizeFraction" format="float" />
```

Example:

```xml
<com.github.rubensousa.gravitysnaphelper.GravitySnapRecyclerView
    android:id="@+id/recyclerView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:snapGravity="start" />
```

## Start snapping

```kotlin
val snapHelper = GravitySnapHelper(Gravity.START)
snapHelper.attachToRecyclerView(recyclerView)
```

<img src="screens/snap_start.gif" width=350></img>

## Center snapping

```kotlin
val snapHelper = GravitySnapHelper(Gravity.CENTER)
snapHelper.attachToRecyclerView(recyclerView)
```

<img src="screens/snap_center.gif" width=350></img>

## Limiting fling distance

If you use  **setMaxFlingSizeFraction** or **setMaxFlingDistance** 
you can change the maximum fling distance allowed.

<img src="screens/snap_fling.gif" width=350></img>


## With decoration

<img src="screens/snap_decoration.gif" width=350></img>

## Features 

1. **setMaxFlingDistance** or **setMaxFlingSizeFraction** - changes the max fling distance allowed.
2. **setScrollMsPerInch** - changes the scroll speed.
3. **setGravity** - changes the gravity of the SnapHelper.
4. **setSnapToPadding** - enables snapping to padding (default is false)
5. **smoothScrollToPosition** and **scrollToPosition**
6. RTL support out of the box

## Nested RecyclerViews

Take a look at these blog posts if you're using nested RecyclerViews

1. [Improving scrolling behavior of nested RecyclerViews](https://rubensousa.com/2019/08/16/nested_recyclerview_part1/)

2. [Saving scroll state of nested RecyclerViews](https://rubensousa.com/2019/08/27/saving_scroll_state_of_nested_recyclerviews/)


## License

    Copyright 2018 The Android Open Source Project
    Copyright 2019 Rúben Sousa
    
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
    
        http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

---