Introduction

Super-fast, super-lightweight sectioned lists for Android

Informations

Creator
nolanlawson
nolanlawson
Git URL:
Language
Java
Min SDK:
Android 4.4
License:
Apache License
Created At:
Nov 26, 2013
Last Updated:
Jun 10, 2017
Star:
80
Fork:
20
Watcher count:
13
Tags

Description

SuperSaiyanScrollView

Version 1.2.0 (changelog)

Super-fast, super-lightweight sectioned lists for Android.

Screenshot

SuperSaiyanScrollView on HTC Magic (Eclair) and Galaxy Nexus (Jelly Bean)

Author

Nolan Lawson

License

Apache 2.0

Installation

Eclipse

Clone the source code:

git clone https://github.com/nolanlawson/SuperSaiyanScrollView.git

Then add the supersaiyan-scrollview folder as a library project dependency on your own project. If you've never worked with an Android library before, here's a good tutorial with screenshots or you can read the official docs.

If you use Proguard, add the following to your proguard.cfg (Gradle handles this automatically):


-keep public class com.nolanlawson.supersaiyan.widget.*

Maven

<dependency>
   <groupId>com.nolanlawson</groupId>
   <artifactId>supersaiyan-scrollview</artifactId>
   <version>1.2.0</version>
</dependency>

Gradle

compile 'com.nolanlawson:supersaiyan-scrollview:1.2.0@aar'

Motivation

Fast-scrolling sectioned lists are one of the most common UI patterns in Android, and yet it's still a pain to implement from scratch. Nothing in the stock Android SDK provides this functionality.

The SuperSaiyanScrollView comes to the rescue with lightning-fast UI elements and helper functions, to make working with sectioned lists easy.

Why "Super Saiyan"? Because:

  • I made it, so I get to name it.
  • It's super-fast, super-powerful, and it kicks (stock) Android's ass.
Their power levels are definitely over 9000.

Usage

In your layout XML file, add a SuperSaiyanScrollView around your ListView:

<com.nolanlawson.supersaiyan.widget.SuperSaiyanScrollView
  android:id="@+id/scroll"
  android:layout_width="match_parent"
  android:layout_height="match_parent">

  <ListView
    android:id="@android:id/list"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:scrollbars="none"
    />

</com.nolanlawson.supersaiyan.widget.SuperSaiyanScrollView>

(I like to set android:scrollbars="none", to remove the omnipresent gray scrollbars and stick with the "fast" blue scrollbars.)

Next, wrap your existing Adapter (e.g. an ArrayAdapter) in a SectionedListAdapter. The SectionedListAdapter uses a fluent "builder" pattern, similar to AlertDialog.Builder:

SectionedListAdapter<MyCoolAdapter> adapter = 
    SectionedListAdapter.Builder.create(this, myCoolAdapter)
    .setSectionizer(new Sectionizer<MyCoolListItem>(){


  @Override
  public CharSequence toSection(MyCoolListItem item) {
    return item.toSection();
  }
})
.sortKeys()
.sortValues()
.build();

Examples

Let's walk through some short examples, which should demonstrate the simplicity and flexibility of the SuperSaiyanScrollView. The source code for these apps is included in the GitHub project, and you can download the APKs here:

Example #1: Countries

In this example, we have a list of countries, which we'd like to sort by continent. The finished app looks like this:

Screenshot

We have a simple Country object:

public class Country {

  private String name;
  private String continent;

  /* getters and setters ... */

  @Override
  public String toString() {
    return name;
  }
}

We use a basic ArrayAdapter<Country> to display the countries:

ArrayAdapter<Country> adapter = new ArrayAdapter<Country>(
        this, 
        android.R.layout.simple_spinner_item, 
        countries);

Next, we wrap it in a SectionedListAdapter. In this case, we'd like to section countries by their continent, sort the continents by name, and sort countries by name:

sectionedAdapter = 
    SectionedListAdapter.Builder.create(this, adapter)
    .setSectionizer(new Sectionizer<Country>(){


  @Override
  public CharSequence toSection(Country input) {
    return input.getContinent();
  }
})
.sortKeys()
.sortValues(new Comparator&lt;Country&gt;() {

  public int compare(Country lhs, Country rhs) {
    return lhs.getName().compareTo(rhs.getName());
  }
})
.build();

A Sectionizer is a simple callback that provides a section name for the given list item. In your own code, this might be a HashMap lookup, a database query, or a simple getter (as in this example).

Notice also that the keys (i.e. the section titles) and the values (i.e. the list contents) can be sorted independently, or not sorted at all. By default, they're sorted according to the input order.

Now, let's try to change the sections dynamically! In the action bar, the user can switch between alphabetic sorting and continent sorting:

alphabetic sorting vs. continent sorting

To do so, we first get a reference to the SuperSaiyanScrollView:

SuperSaiyanScrollView superSaiyanScrollView = 
    (SuperSaiyanScrollView) findViewById(R.id.scroll);

Then, we call the following function whenever the user chooses alphabetic sorting:

private void sortAz() {

  // use the built-in A-Z sectionizer
  sectionedAdapter.setSectionizer(
      Sectionizers.UsingFirstLetterOfToString);

  // refresh the adapter and scroll view
  sectionedAdapter.notifyDataSetChanged();
  superSaiyanScrollView.refresh();
}

Notice that the SectionedListAdapter and SuperSaiyanScrollView need to be informed whenever their content changes.

Next, when the user switches back to continent sorting, we call this function:

private void sortByContinent() {

  // use the by-continent sectionizer
  sectionedAdapter.setSectionizer(new Sectionizer<Country>(){


    @Override
    public CharSequence toSection(Country input) {
      return input.getContinent();
    }
  });
// refresh the adapter and scroll view sectionedAdapter.notifyDataSetChanged(); superSaiyanScrollView.refresh(); }

Notice that you never need to call adapter.sort() or Collections.sort() yourself. The SectionedListAdapter handles everything. And it does so without ever modifying the underlying adapter, which means that view generation is lightning-fast.

Dark theme

Don't like the light overlay? Put on your shades and set ```myapp:ssjn_overlayTheme="dark"``` in the XML:

Screenshot

Black hair or light hair - the choice is yours.

Example #2: Pokémon

This example shows off some of the advanced functionality of the SuperSaiyanScrollView. We have three different sortings, the size of the overlay box changes to fit the text size, and we can dynamically hide both the overlays and the section titles.

Screenshot

Alphabetic vs. by-region sorting

First off, the size of the overlay can be configured in XML. In this example, we start off with a single-letter alphabetic sorting, so we want the overlays to be a bit smaller than normal.

Add a namespace to the root XML tag in your layout XML:

<RelativeLayout
  ...
  xmlns:myapp="http://schemas.android.com/apk/res/com.example.example1"
  ...
  >
</RelativeLayout>

Next, use values prefixed with ssjn_ to define the size of the overlay:

<com.nolanlawson.supersaiyan.widget.SuperSaiyanScrollView
  ...
  myapp:ssjn_overlaySizeScheme="normal">

  <ListView
    ...
    />

</com.nolanlawson.supersaiyan.widget.SuperSaiyanScrollView>

I include the built-in schemes small (for one letter), normal (for most use cases), and large and xlarge (for longer section titles). Section titles of up to two lines (separated by \n) are supported.

Screenshot

Small, normal, large, and xlarge overlays in my AMG Geneva app.

If you want, you can also manually specify the font size, width, height, and text color yourself:

<com.nolanlawson.supersaiyan.widget.SuperSaiyanScrollView
  ...
  myapp:ssjn_overlayWidth="400dp"
  myapp:ssjn_overlayHeight="200dp"
  myapp:ssjn_overlayTextSize="12sp"
  myapp:ssjn_overlayTextColor="@android:color/black" >

  <ListView
    ...
    />
</com.nolanlawson.supersaiyan.widget.SuperSaiyanScrollView>

Now, in the Java source, we have a PocketMonster object:

public class PocketMonster {

  private String uniqueId;
  private int nationalDexNumber;
  private String type1;
  private String type2;
  private String name;

  /* getters and setters */

  @Override
  public String toString() {
    return name;
  }
}

We have a simple PocketMonsterAdapter to define how the monsters are displayed in the list:

public class PocketMonsterAdapter 
    extends ArrayAdapter<PocketMonster> {

  // Constructors...

  @Override
  public View getView(int pos, View view, 
      ViewGroup parent) {


PocketMonster monster = 
    (PocketMonster) getItem(pos);

/* Create and style the view... */

return view;
} }

We wrap this adapter in a SectionedListAdapter that, by default, sections and sorts everything alphabetically:

 adapter = SectionedListAdapter.Builder.create(this, subAdapter)
     .setSectionizer(Sectionizers.UsingFirstLetterOfToString)
     .sortKeys()
     .sortValues(new Comparator<PocketMonster>(){


   @Override
   public int compare(PocketMonster lhs, 
         PocketMonster rhs) {
     return lhs.getName().compareToIgnoreCase(
         rhs.getName());
   }})
 .build();

Notice that we call both sortKeys() and sortValues(), because we want both the section titles and the Pokémon to be ordered alphabetically. Since PocketMonster does not implement Comparable, we defined a custom Comparator.

Now let's say we want to organize the Pokémon by region:

Pokémon sorted by region.

Some quick background: Pokémon are ordered by their "national ID," an integer value that starts at 1 (Bulbasaur) and goes up to 718 (Zygarde). Every time Nintendo releases a new generation of Pokémon games, they add about 100 new monsters, set the game in a new "region," and sell about a bazillion new Pokémon toys.

So basically, we can determine the regions from the Pokémon's ID. We'll define a new Sectionizer, which is called when the user selects "sort by region":

private void sortByRegion() {
  adapter.setSectionizer(new Sectionizer<PocketMonster>() {


@Override
public CharSequence toSection(PocketMonster input) {
  int id = input.getNationalDexNumber();

  // Kanto region will appear first, followed 
  // by Johto, Hoenn, Sinnoh, Unova, and Kalos
  if (id &lt;= 151) {
    return "Kanto (Generation 1)";
  } else if (id &lt;= 251) {
    return "Johto (Generation 2)";
  } else if (id &lt;= 386) {
    return "Hoenn (Generation 3)";
  } else if (id &lt;= 493) {
    return "Sinnoh (Generation 4)";
  } else if (id &lt;= 649) {
    return "Unova (Generation 5)";
  } else {
    return "Kalos (Generation 6)";
  }
}

});

// uses the nat'l pokedex order, since // that's the original input order adapter.setKeySorting(Sorting.InputOrder); adapter.setValueSorting(Sorting.InputOrder); scrollView.setOverlaySizeScheme( OverlaySizeScheme.Large);

// refresh the adapter and scroll view adapter.notifyDataSetChanged(); scrollView.refresh(); }

Notice that we've changed the key and value sorting to Sorting.InputOrder, because now we want to order Pokémon by their national IDs, which was the order the data was read in. (A custom Comparator would have also done the trick.) Additionally, we've increased the size of the overlay to accommodate the longer section text.

Now, let's say we want to organize Pokémon by type. Each Pokémon has at least one elemental type (such as "fire" or "water"), but some have two. Ideally we would like to list Pokémon in multiple categories, so they could appear multiple times in the list.

To do so, we will define a MultipleSectionizer instead of a regular Sectionizer:

private void sortByType() {
  adapter.setMultipleSectionizer(
      new MultipleSectionizer<PocketMonster>() {


@Override
public Collection&lt;? extends CharSequence&gt; toSections(
    PocketMonster monster) {
  String type1 = monster.getType1();
  String type2 = monster.getType2();

  if (!TextUtils.isEmpty(type2)) { // two types
    return Arrays.asList(type1, type2);
  } else { // one type
    return Collections.singleton(type1);
  }
}

}); adapter.setKeySorting(Sorting.Natural); adapter.setValueSorting(Sorting.InputOrder); scrollView.setOverlaySizeScheme(OverlaySizeScheme.Normal);

// refresh the adapter and scroll view adapter.notifyDataSetChanged(); scrollView.refresh(); }

Notice that the key sorting has again changed, this time to Sorting.Natural, which simply sorts alphabetically. Value sorting has changed to Sorting.InputOrder, because we've decided to sort Pokémon by their national IDs.

This works as expected:

Screenshot

Pokémon sorted by type

Notice that Charizard appears in both in the "Fire" and "Flying" sections, since he has two types.

This example app also shows how you can disable the section titles or section overlays, just in case you don't like them. These values can also be set during the Builder chain, using hideSectionTitles() and hideSectionOverlays().

Screenshot

Comparison of hiding overlays and hiding section titles

New in 1.2.0!

Thanks to some awesome work by michaldarda, you can now specify a custom SectionTitleAdapter or layout for the SectionTitleAdapter. If you use a layout, it should be an XML layout resource with attribute android:id="@+id/list_header_title" to indicate the header text. (The default one can be found here if you want to just modify that.)

import com.nolanlawson.supersaiyan.SectionTitleAdapter;

sectionedAdapter = SectionedListAdapter.Builder.create(this, subAdapter)
    .setSectionTitleLayout(R.layout.my_layout_id)
    // alternative version
    .setSectionTitleAdapter(new MySubclassOfSectionTitleAdapter())    
    .build();

Details

See the original blog post for some historical insight.

This project was originally derived from my own CustomFastScrollViewDemo, which was based on a modification of the Android "Contacts" app. I can no longer find the original source, nor the original author. But kudos to you, mysterious stranger!

Changelog

  • 1.2.0
    • Specify a custom list header (#7)
    • Fix for deta not being refreshed (#8)
  • 1.1.1
    • Fix potential issue when there are no XML attributes (#3)
  • 1.1.0
    • Convert to Gradle
    • Add dark theme (#1)
  • 1.0.0
    • Initial release.

Discussion