Building First App

Basic Back Screen application structure

The YotaPhone 2 Back Screen application consists of a Back Screen FullView app and/or Back Screen widget. The developer can choose the parts he wants to include.

FullView or Fullscreen App Refers to fullscreen apps designed specifically for the Always-on Screen, following YotaPhone2 guidelines and principles. A fullscreen App that runs on YotaPhone's Always-on Screen or has a Widget designed for it can be considered an Application for YotaPhone.

Widget Refers to YotaPhone's Always-on Screen Widgets — non full-screen application modules put on a Panel. Widgets usually pull all of their content from their respective parent fullscreen application.

Switching between widget view and full screen view is made by tapping the widget. Taps in different areas may lead to different full screen views:
• Tapping the body or the heading of the post in the RSS Back Screen widget will open a full-screen view of the post.
• Tapping «… more news for you» will open a full-screen list view which contains a list of recent RSS posts.

Getting Started

Before you start with creating your first back screen application, be sure you have already set up:
• Android SDK
• Android API 21 SDK Platform
• YotaPhone2 Add-On SDK
• Eclipse IDE (optionally)
Note: You can use Android API 22 if you migrate to a new SDK. Find more info here.

Eclipse is used here as an example but you can use any other capable IDE. If you have no Android platform development experience, you can try out this class beforehand.

Creating an Android Project in Eclipse

1. To create an Android project select File > New > Android Application Project. Fill the Application Name, Project Name and Package Name as you want. The field Compile With should be YotaPhone2 Add-On L Preview (YotaDevices) (API 21). You can see an example below:

Create Application in Eclipse

2. Fill others application settings as you want.

3. Once the project is created, you can see android.jar and the YotaPhone2 Add-On SDK library com.yotadevices.yotaphone2.sdk.jar in your Package Explorer:

Project structure in Eclipse

Creating an Android Project in Android Studio

1. To create an Android project select Start a new Android Studio project. Fill the Application Name and Company Domain, select Project Location as you want. Click Next.

2. In the next screen, just select a Minimum SDK of YotaPhone2 Add-On L Preview (YotaDevices) (API 21) as shown below:

Create Application in Android Studio

3. Fill others application settings as you want.

4. Once the project is created, you can see android.jar and the YotaPhone2 Add-On SDK library com.yotadevices.yotaphone2.sdk.jar in your Project structure:

Project structure in Android Studio

5. Now, you could change minSdkVersion into Gradle file to other value (as you want), for example: minSdkVersion=16. Also, please, make sure that you use following Gradle plugin version (or higher): com.android.tools.build:gradle:1.1.2

Preparing app to using the YotaPhone2 back screen features

To use the YotaPhone2 back screen features in your app, you need to include YotaPhone2 Add-On SDK library definition in the app manifest (AndroidManifest.xml file). Please, add the following to the application section:

<!-- Adding YotaPhone SDK library -->
<uses-library android:name="com.yotadevices.yotaphone2.sdk.v2"
            	android:required="true" />

When "android:required="true" is declared for a feature, it means that the application cannot, or is not designed to function, when the specified feature is not present on the device (it means that this app will only for YotaPhone2).

You are now ready to create a back screen activity for your application.

Creating a Full View Activity for the back screen (Backscreen Service)

1. To add a back screen activity to your project you should create class that extends BSActivity with the following content:

(file “MyBSActivity.java”)

public class MyBSActivity extends BSActivity {
	@Override
	protected void onBSCreate() {
		super.onBSCreate();
		setBSContentView(R.layout.bs_activity);
	}
}

You should prepare the layout file for this back screen activity. For example:

(file “res/layout/bs_activity.xml”)

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical" >
 
	<TextView
	android:layout_width="fill_parent"
	android:layout_height="0dip"
	android:layout_weight="1"
	android:background="#000000"
	android:gravity="center"
	android:text="Hello YotaPhone!"
	android:textColor="#ffffff"
	android:textSize="65dip" />
 
</LinearLayout>

2. Since MyBSActivity extends from the back screen activity class BSActivity, which itself extends from Service, it needs to be specified in the manifest file. Add the following to the application section:

<!-- Service for working with a back screen -->	
<service android:name=".MyBSActivity" android:exported="false" />

3. The back screen service is ready now. We can start it from our MainActivity:

	@Override
	protected void onStart() {
		super.onStart();
		Intent bsIntent = new Intent(this, MyBSActivity.class);
		this.startService(bsIntent);
	}

4. Run your application via Run > Run. It should print “Hello, YotaPhone!” on the back screen.

Note: You can launch your new back screen activity from another back screen activity and you can move between them by clicking the back button on the navigation panel.

Creating a Min View widget for the back screen (App Widget)

Creating widgets for the back screen is very similar to creating standard Android widgets. To create an App Widget, you need the following:

• AppWidgetProviderInfo object - describes the metadata for an App Widget, such as the App Widget's layout, update frequency, and the AppWidgetProvider class. This should be defined in XML.
• AppWidgetProvider class implementation - defines the basic methods that allow you to programmatically interface with the App Widget, based on broadcast events. Through it, you will receive broadcasts when the App Widget is updated, enabled, disabled and deleted.
• View layout - defines the initial layout for the App Widget, defined in XML.

For more information about App Widgets, please see the official guide.

1. First, declare the AppWidgetProvider class in your application's AndroidManifest.xml file:

<!-- App Widget that can work on a back screen -->
<receiver android:name="com.yotadevices.samples.hello.BSWidget" > 
	<intent-filter> 
		<action android:name="android.appwidget.action.APPWIDGET_UPDATE" /> 
	</intent-filter>
 
	<!--Front screen widget settings --> 
	<meta-data android:name="android.appwidget.provider" 
	android:resource="@xml/fs_widget_info" /> 
 
	<!-- Back screen widget settings --> 
	<meta-data android:name="com.yotadevices.yotaphone.bs_provider" 
	android:resource="@xml/bs_widget_info" /> 
 
</receiver>

Note: If this meta-data about the back screen widget settings isn't added to the Android Manifest, they will not be displayed on the back screen of the device.

2. AppWidgetProviderInfo defines the essential qualities of an App Widget, such as its minimum layout dimensions, its initial layout resource, how often to update the App Widget, and (optionally) a configuration activity to launch at creation. Define the AppWidgetProviderInfo object in an XML resource using a single<appwidget-provider> element and save it in the project's res/xml/ folder.

Here is an example for front screen Widget settings: (file “res/xml/fs_widget_info.xml”)

<?xml version="1.0" encoding="utf-8"?>
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android" 
android:minWidth="75dp" 
android:minHeight="25dp" 
android:updatePeriodMillis="0" 
android:initialLayout="@layout/bs_widget"
android:resizeMode="horizontal|vertical"
android:widgetCategory="home_screen"/>

Note: If you don't want your widget to be visible in the standard Android widget list, but want it to be visible in the back screen widget list only, then set android:widgetCategory="".

3. For the back screen Widget settings, the developer must include at least one supported widget size. A back screen Widget can support several different sizes: small, medium, large, extra_large and full_screen. You can find out more about widget sizes here. Indents between widgets are set by the Dashboard Manager and cannot be changed.

If a widget does not support white theme natively it can make himself invertable. If a widget is invertable then YotaHub will invert colors on White device. In the following example the widget is invertable on small and medium sizes and not invertable on large size.

Here is an example for back screen Widget settings: (file “res/xml/bs_widget_info.xml”)

<?xml version="1.0" encoding="utf-8"?>
<backscreen-widget-provider 
	xmlns:android="http://schemas.android.com/apk/res/android"
	xmlns:sdk="http://schemas.android.com/apk/com.yotadevices.sdk"
	sdk:size="small|medium"
	sdk:invertable="small|medium"/>

4. In the next step, you should define an initial layout for your App Widget in XML and save it to the project res/layout/ directory. Widget layouts are based on RemoteViews, which do not support every kind of layout or view widget. Below, you can see an example:

<?xml version="1.0" encoding="utf-8"?>
<Button xmlns:android="http://schemas.android.com/apk/res/android"
  android:layout_width="wrap_content" 
  android:layout_height="wrap_content" 
  android:text="Launch BSActivity" 
  android:id ="@+id/button" 
  android:textColor="@android:color/white"/>

5. Now you are ready to create a back screen widget class (extends AppWidgetProvider). If your App Widget doesn't create temporary files or databases, or perform other work that requires clean-up, then onUpdate() may be the only callback method you need to define.

For example, if you want an App Widget with a button that launches a Full View (Back Screen Activity) on the back screen when clicked, you can use the following implementation of AppWidgetProvider:

public class BSWidget extends AppWidgetProvider {
 
	@Override
	public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
		super.onUpdate(context, appWidgetManager, appWidgetIds);
 
		Intent intent = new Intent(context, MyBSActivity.class); 
		PendingIntent pendingIntent = PendingIntent.getService(context, 0, intent, 0);
 
		RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.bs_widget); 
		views.setOnClickPendingIntent(R.id.button, pendingIntent);  
		appWidgetManager.updateAppWidget(appWidgetIds, views);
	}
}

6. That’s it. In order to display your widget on the Back Screen, run the “YotaHub” application, delete any existing widget from the panel if needed (or add new panel) and add your widget from the list.

Note: You can find this sample project and other examples in the “Add-On” directory (<android-sdk_dir\add-ons\addon-yotaphone2_add-on_l_preview-yotadevices-21\samples\>). "Yotaphone_hello" is the name of the project discussed in this manual.