Home

Awesome

<img src ="https://upload.wikimedia.org/wikipedia/commons/b/b5/Kotlin-logo.png" width=24> RecyclerViewFastScroller

Github release Maven Central Code size Android Weekly #317 Kotlin Weekly #101

A simple, easy to use and configurable fast scroller for RecyclerView

<img src = "https://github.com/quiph/RecyclerView-FastScroller/raw/master/graphics/recording_contacts.gif" width=240> <img src = "https://github.com/quiph/RecyclerView-FastScroller/raw/master/graphics/recording_countries.gif" width=240> <img src = "https://github.com/quiph/RecyclerView-FastScroller/raw/master/graphics/recording_numbers.gif" width=240>

Adding the dependency

implementation 'com.quiph.ui:recyclerviewfastscroller:1.0.0'

Java-only project?

As Kotlin compiles to Java, there's no need to externally add the Kotlin runtime or any other Kotlin dependencies when using this. Also the library is 100% compatible with Java and requires no migration of the base project to Kotlin.

Usage:

The base layout type for this fast scroller is a RelativeLayout so creating a simple vertical fast scroller is as simple as adding elements as children to the RecyclerViewFastScroller layout tag

<com.qtalk.recyclerviewfastscroller.RecyclerViewFastScroller
        android:layout_width="match_parent"
        android:id="@+id/fastscroller"
       android:layout_height="match_parent">
        <android.support.v7.widget.RecyclerView
                    android:layout_width="match_parent"
                    android:layout_height="match_parent"/>
        ....
        other view tags can also come here
        ....
</com.qtalk.recyclerviewfastscroller.RecyclerViewFastScroller>

Since the fast scroller extends a RelativeLayout other view tags can also be added to it, with the rule being that the RecyclerView on which the fast scroller functionality needs to be added be the first element in the ViewGroup

Programmatically adding the RecyclerView

If the RecyclerView to be added to the fast scroller is not available during layout creation time, the same can be done programmatically by calling the attachFastScrollerToRecyclerView method on the RecyclerView

Linking with items:

To reflect the item on the index of the top-most visible item, make the adapter implement the OnPopupTextUpdate interface, which overrides the method onChange(int index) which passes the index of the element whose info needs to be displayed in the popup.

The CharSequence to be displayed should be returned in this method.

Ex:

class MyAdapter : RecyclerView.Adapter<SomeViewHolder>, OnPopupTextUpdate{
// ....
override fun onChange(position: Int): CharSequence {
   val header = // compute value for header using position
   return header                  
   }
}

Getting fast scroller callbacks:

To get the callback from the fast scroller for different states, a listener can be added using the setHandleStateListener which accepts an interface of type HandleStateListener which has the following callback methods:

Customizable XML Attributes:

Advanced usage:

Check the sample file AdvancedFragment and AdvancedAdapter for example usage

Ex:

class MyAdapter : RecyclerView.Adapter<SomeViewHolder>, OnPopupViewUpdate{

    override fun onChange(position: Int, popupTextView: TextView) {
       // Do something with the TextView here
       popupTextView.background = Color.RED // change some values etc
       }
}

The popupDrawable attribute and the popupTextStyle attributes can be used to create different kinds of elements, shapes and text appearance combinations, for example like the popup similar to the Google Dialer app:

<img src = "https://raw.githubusercontent.com/quiph/RecyclerView-FastScroller/master/graphics/screenshot_contacts1.png" width = 320>

Check the sample to view the implementation. Many such shapes and text styles can be created.

Proguard:

There is no need for any additional proguard rules when using this.

Contributing

Thank you for your interest :)

To start contributing, you can check out the issues section with the tag "Good first issue" to start working on the low-hanging fruits. Once you feel comfortable to contribute, fork the project and raise a PR, we'd be happy to review it <3

Creating a Pull Request

Our team follows the GitHub pull request workflow: fork, branch, commit, pull request, review, merge. If you're new to GitHub, check out the official guides for more information.

An example commit message summary looks like, For #5: Upgrade gradle to v1.3.0.

Please follow these guidelines for your pull requests:

If your code is not approved, address the suggested comments, push your changes, and re-request review from your reviewer again.

Merging

After your code has been approved and the tests pass, your code will be merged into master by the core team. When merging, we use GitHub's "Rebase and merge":

Building the source

To build the aar using using gradle, simply run the build command, ./gradlew build this will build and place the aars in the outputs/aar folder inside the library module. The final path may look something like:

"${rootProject.projectDir}/recyclerviewfastscroller/build/outputs/aar"

This path has a number of aars in it, (debug and release variants namely). To use these aars in the sample, simple uncomment the following line in build.gradle for sample

// implementation files("${rootProject.projectDir}/recyclerviewfastscroller/build/outputs/aar/recyclerviewfastscroller-release.aar")

Don't forget to comment the project/ module dependency above it. Re-sync the project and run the sample to test how the compiled version would behave.

Uploading to maven central:

We will be using the Nexus Software Repository for pushing our aars to maven-central, there are different methods to do this, another simple way is to upload to bintray and then push to maven-central from there, which one to use can completely depend upon the developer.

Detailed explanation here.

Once the environment is setup as mentioned in the gist, run the following command:

./gradlew clean build uploadArchives

TODO: