Android SDK Versions Tutorial With Kotlin

Backward Compatibility

The Android SDK is by default forward compatible but not backward compatible — this means that an app that is built with and supports a minimum SDK version of 3.0 can be installed on any device running Android versions 3.0 and upwards — but not on devices running Android versions below 3.0.

Since the Android SDK is not backward compatible, you should choose the minimum SDK carefully. This means striking a balance between supporting a wide range of devices and designing an app that implements useful features in later SDK versions.

For example, when Android 3.0 was released in 2011, the Action Bar was unleashed on the Android Community. Since the Action Bar was only supported in Android 3.0 and later, using it in an app meant choosing either a cool user interface or supporting devices that ran older versions of the SDK. Sometimes you can’t have your honeycomb and eat it, too. :[

Or can you? To help with the Action Bar issue, the Android Support Library introduced a backward-compatible version in the v7-appcompat Support Library. So it would allow developers to support older versions of the SDK and still use the latest Action Bar APIs in their apps. Sweet! Honeycomb for everyone!

Take a deeper look at what the Support Library does and how it works.

Android Support Libraries

A wide range of components make up what is referred to as the “Support Library” or “Support Libraries,” and they can be categorized in two groups:

The goal of this first release was to allow developers to backport the ActionBar to devices running Ice Cream Sandwich level. This gave API parity to the framework across as many API Levels as possible. Since then, the AppCompat library has continued to evolve. And with Android Lollipop, the Support Library is now at the point where the API is equivalent to the framework itself — the first time that has ever happened. :]

• The AppCompat library: The intention here is to make sure all (or most) of the framework APIs for the latest API Level have been backported to earlier versions and can be found in this single library. The first version of AppCompat was released at Google I/O 2013.

  The goal of this first release was to allow developers to backport the ActionBar to devices running Ice Cream Sandwich level. This gave API parity to the framework across as many API Levels as possible. Since then, the AppCompat library has continued to evolve. And with Android Lollipop, the Support Library is now at the point where the API is equivalent to the framework itself — the first time that has ever happened. :]

• Others: The rest of the libraries that make up the Support Library essentially provide new functionality with the same consideration for backward compatibility (palette, gridview, gridlayout, recycler view, material design widgets).

When you break these up into independent libraries, you can pick and choose the ones you need in your project. It’s important to note that each support library is backward-compatible to a specific API Level. And they are usually named based on which API Level they are backward-compatible to. For example, v7-appcompat provides backward compatibility to API Level 7.

You can find the full list of components that fall under the Support Library in the Android documentation.

AndroidX Support Libraries

Using an Android Support Library

Time to see an Android Support Library in action! Open MainActivity.kt. As you may have noticed in the onCreate() method, the app uses a Toolbar (which is part of the material design patterns) instead of an Action Bar.

The Toolbar was added in API 21 (Android Lollipop) as a flexible widget that can be used anywhere in layouts, be animated and change it’s size, unlike the Action Bar.

Thanks to AppCompat, that feature has been back-ported all the way to API 14, which is code-named Ice Cream Sandwich (are you hungry yet?). You’re going to use the v7-appcompat Support Library to extend your app’s compatibility to a minSdkVersion of 16.

Update Build File

First, add google() to the Maven repositories in your project-level build.gradle file, if it’s not already there:

repositories {
    jcenter()
    google()
}

Now, open build.gradle for the app module and add the following to the dependencies section:

implementation "com.android.support:appcompat-v7:28.0.0"

By adding this, you’re declaring the appcompat-v7 Support Library as a dependency for your app. You can ignore the warning to use a newer version of the Support library. Though you may update, it’s recommended you stick to the one in this tutorial.

Next, change the minSdkVersion attribute to 16.

minSdkVersion 16

Here, you’re declaring that the app should be able to run on devices with Android SDK version 4.1.2. Now try running your app on an emulator running API Level 16. You should see the following exceptions in the logcat:

The important line to look for is:

Caused by: java.lang.ClassNotFoundException: android.widget.Toolbar

The ClassNotFoundException error indicates that there is no such class in the SDK version you’re running the app against. Indeed, it’s only available in API Level 21, while you’re currently running API Level 16.

Updating for Backward Compatibility

You’re going to update the code to use the backward-compatible version of Toolbar. Open MainActivity.kt, and update the android.widget.Toolbar import statement to match the following:

import android.support.v7.widget.Toolbar

This replaces the SDK import with one from the AppCompat library.

Next import the AppCompatActivity from the AppCompat library:

import android.support.v7.app.AppCompatActivity

Next update the MainActivity class definition line so that it inherits from AppCompatActivity:

class MainActivity : AppCompatActivity(), ContinentSelectedListener

Once again, you’re replacing a class from the latest SDKs with one that exists in the Support Library.

You now need to work through the class and replace some method calls with their Support Library equivalents:

• Find the call to setActionBar(toolbar) at the end of the onCreate() method body and update it to setSupportActionBar(toolbar).
• Find the calls to actionBar? in onContinentSelected(), goToContinentList(), and onBackPressed() and replace both of them with supportActionBar?.
• Replace the calls to fragmentManager() in onContinentSelected() and goToContinentList() with supportFragmentManager().
• Change the code in goToContinentList() to fix the error in replacing the fragment:

    val fragment = MainFragment.newInstance(continentNames)
    supportFragmentManager
        .beginTransaction()
        .replace(R.id.frameLayout, fragment)
        .commit()
    mainFragment = fragment