Introduction
– Android TV application hands on tutorial 1

androidtvapptutorial6

[updated 2015.11.16]: Revise (sentence structure refactoring).

Android TV application development introduction

Currently, we have still not enough introduction for Android TV application development yet. In this series of tutorial, I will introduce how to develop Android TV application.
The aim of this post is to understand Android “TV” specific code implementation, especially focusing on UI implementaion.

Because UI is one of the biggest difference between Android phone app and Android TV app. We need to make UI suitable for TV usage, for example we should make an app so that we can navigate the application only using ↑↓→← direction keys, instead of touchpad navigation. Because user uses remote controller, and cannot use “touch screen” function with TV. To achieve this requirement, Android open source project is providing Leanback Support library (android.support.v17.leanback) so that developers can easily implement UI which satisfies these requirements and thus suitable for TV usage. This tutorial mainly explain the usage of this Leanback library.

The target of this post is people those who,,,

  • developed Android app before, but not familiar with Android TV app.
  • begginer – intermediate level

Since Eclipse support will be finished at the end of 2015, Android studio will be used for the IDE to develop Android TV apps (So please download and setup Android studio, if you have not yet done!). Note that most of the code introduced here is from AOSP android TV sample source code. Basically this tutorial is just detail explanation of this sample source code. Let’s begin.

Launch new Android TV application

  1. Launch Android studio,

New project

 Application name: AndroidTVappTutorial

 Company Domain: corochann.com ( or you can use your own domain name )

androidtvapptutorial1

Target Android Devices

androidtvapptutorial2

Add an activity to TV

androidtvapptutorial3

Select “Add No Activity” and Finish

Android studio automatically generate the source codes to start this Tutorial.

The source code of this phase is uploaded on github.

  1. Add activity

At first, let’s make activity. Right click on “com.corochann.androidtvapptutorial”, and choose

New -> Activity -> Blank activity

Check “Launcher Activity”.

I will start from making blank activity, named “MainActivity“. 

Android studio now generate 2 files, Java class & layout/activity_main.xml. (we don’t use res/menu/menu_main.xml)

* Note: We can also find “Android TV activity”. When you select this, it will create too match files at the same time. It’s a really helpful reference, but difficult to understand what kind of functions each files takes care of. So I will create these files from scratch in this post so that we can understand each source code’s responsibility. Many of the implementation in this post is referencing this official sample program.

Next, we want to design UI of MainActivity by creating MainFragment.

  1. Add fragment

Right click on the package name (in my case com.corochann.androidtvapptutorial)

New -> Java Class -> Name: MainFragment

*  Instead of above procedure, if we choose New -> Fragment -> Blank fragment Uncheck “Create layout XML?”, it makes too match sample source code.

First, modify activity_main.xml as follows so that it only displays mainfragment.

* Click right-top “<>” icon on the code, if you want to copy & paste.

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools" android:id="@+id/main_browse_fragment"
    android:name="com.corochann.androidtvapptutorial.MainFragment" android:layout_width="match_parent"
    android:layout_height="match_parent" tools:context=".MainActivity" tools:deviceIds="tv"
    tools:ignore="MergeRootFrame" />

Second modify MainFragment as follows.

We will make this MainFragment as a sub-class of BrowseFragment.

BrowseFragment class is supplied by Android SDK Leanback library, and it creates standard UI for Android TV application which we will see through this Tutorial.

package com.corochann.helloandroidtvfromscrach;
 
import android.os.Bundle;
import android.support.v17.leanback.app.BrowseFragment;
import android.util.Log;
 
public class MainFragment extends BrowseFragment {
    private static final String TAG = MainFragment.class.getSimpleName();
 
    @Override
    public void onActivityCreated(Bundle savedInstanceState) {
        Log.i(TAG, "onActivityCreated");
        super.onActivityCreated(savedInstanceState);
 
    }
}

(I) Build and Run it!

androidtvapptutorial5

BrowseFragment consists of HeadersFragment & RowsFragment.
Here, you can see HeaderFragment (header) part at the right side, and RowsFragment (contents) part at the left side. We will design this Header & Row combination in the following.

Before that, let’s implement UI for main color & title of this application.

source code until here is uploaded on github.

  1. Adding setupUIElements() to MainFragment.java

We will add setupUIElements() method inside MainFragment.java, to set up application information. 

    @Override
    public void onActivityCreated(Bundle savedInstanceState) {
        Log.i(TAG, "onActivityCreated");
        super.onActivityCreated(savedInstanceState);

        setupUIElements();
        
    }

    private void setupUIElements() {
        // setBadgeDrawable(getActivity().getResources().getDrawable(R.drawable.videos_by_google_banner));
        setTitle("Hello Android TV!"); // Badge, when set, takes precedent
        // over title
        setHeadersState(HEADERS_ENABLED);
        setHeadersTransitionOnBackEnabled(true);

        // set fastLane (or headers) background color
        setBrandColor(getResources().getColor(R.color.fastlane_background));
        // set search icon color
        setSearchAffordanceColor(getResources().getColor(R.color.search_opaque));
    }

We have set 

  • Application title or Application icon
  • Brand color

Color information is referenced from colors.xml, which we haven’t made yet. Right click res/values and choose

New -> values Resource file
File name: colors.xml -> “OK”
Write below.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="fastlane_background">#0096e6</color>
    <color name="search_opaque">#ffaa3f</color>
</resources>
colors
colors are shown in left side of text editor in Android studio

(II) Build and Run!

Now you can see title is shown on top-right, and header color = BrandColor on left side has changed.

androidtvapptutorial6

You can also use setBadgeDrawable() method instead of setTitle() method. As written in the comments of above code as “Badge, when set, takes precedent”, the title will change to logo if setBadgeDrawable() is used (See below picture). You can set either one of “title logo icon” by setBadgeDrawable or “title string” by setTitle.

AndroidTVsampleApp
If you use setBadgeDrawable(), logo image will appear instead of title (String) in the top right.

Source code until here is uploaded on github.

  1. Modify Android Manifest.

You may notice that application icon will not be shown in your Leanback Launcher (Android TV home launcher app) until now.
We need some declaration in our app to be considered as Android TV app. Modify AndroidManifest.xml as following.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.corochann.androidtvapptutorial" >


    <!-- TV app need to declare touchscreen not required -->
    <uses-feature
        android:name="android.hardware.touchscreen"
        android:required="false" />

    <!--
     true:  your app runs on only TV
     false: your app runs on phone and TV -->
    <uses-feature
        android:name="android.software.leanback"
        android:required="true" />


    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/Theme.Leanback" >
        <activity
            android:name=".MainActivity"
            android:icon="@drawable/app_icon_your_company"
            android:label="@string/app_name"
            android:logo="@drawable/app_icon_your_company" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

and I put app_icon_your_compan.png in main/res/drawble/ folder.

(III) Build and Run!

To show activity icon in Leanback launcher

You can show activity icon in Leanback launcher by declaring intent-filter.

 <category android:name="android.intent.category.LEANBACK_LAUNCHER" />

Also, the icon is specified in activity tag,

        <activity
            android:name=".MainActivity"
            android:icon="@drawable/app_icon_your_company"
            android:label="@string/app_name"
            android:logo="@drawable/app_icon_your_company" >

            ...
manifest_activity
Activity icon will appear in Leanback Launcher.

To show application icon in Leanback launcher

You can show application icon by declaring, 

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/Theme.Leanback" >

        ...

Note that activity icon and application icon are different.

manifest_application
application icon will appear in your Downloaded apps list.

For the Android manifest setting for Android TV, please refer details in official Android developers page.

Next chapter, Construction of BrowseFragment – Android TV application hands on tutorial 2, I will explain notion of BrowseFragmentHeadersFragmentRowsFragment, Adapter and Presenter to show selectable objects in our app.

References

no suitable constructor found for HeaderItem(int,String,)

I got following error when I try to build android TV sample application.

D:\workspace\androidstudio\AndroidTVsample\app\src\main\java\com\corochann\androidtvsample\MainFragment.java
Error:(109, 33) error: no suitable constructor found for HeaderItem(int,String,<null>)
constructor HeaderItem.HeaderItem(long,String) is not applicable
(actual and formal argument lists differ in length)
constructor HeaderItem.HeaderItem(String) is not applicable
(actual and formal argument lists differ in length)
Error:(113, 33) error: no suitable constructor found for HeaderItem(int,String,<null>)
constructor HeaderItem.HeaderItem(long,String) is not applicable
(actual and formal argument lists differ in length)
constructor HeaderItem.HeaderItem(String) is not applicable
(actual and formal argument lists differ in length)
D:\workspace\androidstudio\AndroidTVsample\app\src\main\java\com\corochann\androidtvsample\PlaybackOverlayFragment.java
Error:(316, 29) error: no suitable constructor found for HeaderItem(int,String,<null>)
constructor HeaderItem.HeaderItem(long,String) is not applicable
(actual and formal argument lists differ in length)
constructor HeaderItem.HeaderItem(String) is not applicable
(actual and formal argument lists differ in length)
D:\workspace\androidstudio\AndroidTVsample\app\src\main\java\com\corochann\androidtvsample\VideoDetailsFragment.java
Error:(156, 33) error: no suitable constructor found for HeaderItem(int,String,<null>)
constructor HeaderItem.HeaderItem(long,String) is not applicable
(actual and formal argument lists differ in length)
constructor HeaderItem.HeaderItem(String) is not applicable
(actual and formal argument lists differ in length)
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Error:Execution failed for task ':app:compileDebugJava'.
> Compilation failed; see the compiler error output for details.

The reason of this error happens is because the definition of the constructor HeaderItem.HeaderItem(long,String) has changed. We need to change

from HeaderItem(id, string, null) to HeaderItem(id, string).

So we need to delete “null” argument for all occurrences in the function.

String types not allowed (at ‘slideEdge’ with value ‘end’)

I got following error when I try to build android TV sample application.

TVDemoApp\app\build\intermediates\exploded-aar\com.android.support\leanback-v17\22.1.1\res\transition-v22\lb_browse_entrance_transition.xml
Error:(26, 26) String types not allowed (at 'slideEdge' with value 'end').
TVDemoApp\app\build\intermediates\exploded-aar\com.android.support\leanback-v17\22.1.1\res\transition-v22\lb_browse_return_transition.xml
Error:(21, 26) String types not allowed (at 'slideEdge' with value 'start').
Error:(30, 26) String types not allowed (at 'slideEdge' with value 'end').
Error:Execution failed for task ':app:processDebugResources'.
> com.android.ide.common.internal.LoggedErrorException: Failed to run command:
C:\Users\corochann\AppData\Local\Android\sdk\build-tools\21.1.1\aapt.exe package -f --no-crunch -I C:\Users\corochann\AppData\Local\Android\sdk\platforms\android-21\android.jar -M D:TVDemoApp\app\build\intermediates\manifests\full\debug\AndroidManifest.xml -S D:TVDemoApp\app\build\intermediates\res\debug -A D:TVDemoApp\app\build\intermediates\assets\debug -m -J D:TVDemoApp\app\build\generated\source\r\debug -F D:\workspace\github\bugfix_episode_4\episode_1\TVDemoApp\app\build\intermediates\res\resources-debug.ap_ --debug-mode --custom-package com.sgottard.tvdemoapp -0 apk --output-text-symbols D:TVDemoApp\app\build\intermediates\symbols\debug
Error Code:
1
Output:
D:TVDemoApp\app\build\intermediates\res\debug\transition-v22\lb_browse_entrance_transition.xml:23: error: Error: String types not allowed (at 'slideEdge' with value 'end').
D:TVDemoApp\app\build\intermediates\res\debug\transition-v22\lb_browse_return_transition.xml:18: error: Error: String types not allowed (at 'slideEdge' with value 'start').
D:TVDemoApp\app\build\intermediates\res\debug\transition-v22\lb_browse_return_transition.xml:27: error: Error: String types not allowed (at 'slideEdge' with value 'end').

How to fix

You need to update configuration of compile SDK version.

update build.gradle (Module: app) as follows.

1. specify compileSdkVersion as 22, not 21.

    compileSdkVersion 22

2. specify dependencies library version as

compile ‘com.android.support:recyclerview-v7:22.1.1
compile ‘com.android.support:leanback-v17:22.1.1
compile ‘com.android.support:appcompat-v7:22.1.1

and build again.

Reference: http://stackoverflow.com/questions/29149362/androidtv-leanback-master-build-errors

Plugin with id ‘android-sdk-manager’ not found

When you face this bug when trying to build Android source code, try following.

Add below inside “dependencies” of top folder of build.gradle (Project: TVDemoApp)

        classpath ‘com.android.tools.build:gradle:1.0.0’
        classpath ‘com.jakewharton.sdkmanager:gradle-plugin:0.12.0’

Reference:

Building Android TV sample application

AndroidTVsampleApp

Let’s look how Android TV app works by building this sample application.

At the time of writing (2015/6/25), I faced a compile error for building default sample application  for Android TV. I wrote another posts that how to resolve these issues, which are the temporary counter measure until the errors will be fixed by AOSP.

Environment

Android studio version: 1.2.2 Build 141.1980579
SDK version: API level 21 & 22.

Procedure

1. Launch Android studio → Start a new Android Studio project

2. “New project” display, fill in below.

Application name: use your own preference (Ex. HelloAndroidTV)
Company Domain: use your own preference (Ex. yourname.com)

and go “Next”.

3. “Target Android Devices” display

Uncheck “Phone and Tablet” (It is checked by Default.)
Check “TV” with Minimum SDK API level 21.

and go “Next”.

4. “Add an activity to TV”,

Select “Android TV Activity”

and go “Next”

5. “Customize the Activity” display,

Name of the Activities are already filled by default as

  • Activity Name: Main Activity
  • Main Layout Name: activity_main
  • Main Fragment: MainFragment
  • Title: MainAcitivity Title
  • Details Activity: DetailsActivity
  • Details Layout Name: activity_details
  • Details Fragment: VideoDetailsFragment

you can just press “finish” without changing names for this time.

After that, Android studio will auto generate codes, after generation click “Run app” button (shown as green triangle button) to build the source code.

If you get compile error…

Please refer following for fixing bugs.

  1. Plugin with id ‘android-sdk-manager’ not found
  2. String types not allowed (at ‘slideEdge’ with value ‘end’)
  3. no suitable constructor found for HeaderItem(int,String,)

Build it and try it!

If successful, you can launch an application shown at the top of this page. You can also try to go around inside the apps, see content details, and watch trailer!