×
Namespaces

Variants
Actions
(Difference between revisions)

Creating widgets for your Nokia X platform applications

From Nokia Developer Wiki
Jump to: navigation, search
spiretos (Talk | contribs)
(Spiretos -)
spiretos (Talk | contribs)
m (Spiretos -)
Line 31: Line 31:
  
 
<gallery widths="240px" heights="400px">
 
<gallery widths="240px" heights="400px">
File:NokiaXWidget1.png|The widget in the Home Screen
+
File:NokiaXWidget3.png|The widget in the Home Screen
 
File:NokiaXWidget2.png|The widget after tapped
 
File:NokiaXWidget2.png|The widget after tapped
 
</gallery>
 
</gallery>

Revision as of 00:56, 15 April 2014

This article shows how to create widgets for your Nokia X platform applications.

Article Metadata
Tested with
Devices(s): NokiaX emulator
Article
Created: spiretos (14 Apr 2014)
Last edited: spiretos (15 Apr 2014)

Note.pngNote: This is an entry in the Nokia X Wiki Challenge 2014Q1

Contents

Introduction

Widgets are miniature application components that can be embedded in the Home Screen. Of course, for Nokia developers, Widget development isn't new. We've used them before on Symbian as WRT Widgets and in Windows Phone as Live Tiles. In NokiaX software platform we have App Widgets. Their purpose remains the same. Show useful information, allow the user to quickly interact with our application without even opening it and be one additional attractive entry point for the application.

This article shows how to create and update an App Widget to be used for your applications. This particular widget is used alongside with a note keeping application. The user will place it in the Home Screen in order to immediately know the amount of notes and the number of those that are important. We will also try to make it look and behave like a Windows Phone Live Tile. The final result looks like the images below.

Building blocks of a Widget

We need three things in order to create an App Widget.

  • AppWidgetProviderInfo

An xml file where we define metadata for the widget.

  • Layout

Finally we need to create an XML layout file to define how our widget will look like.

  • AppWidgetProvider

This is a Java class we need to extend. This class will provide us the functions that allow us to update and interact with our widget.

Let's see them one by one.

AppWidgetProviderInfo

This is an XML file that should be placed it in the project's Resources folder. It is used to describe the widget's metadata like its size, its update frequency, the layout used to draw it and more. For our case this is the XML file.

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
android:minWidth="40dp"
android:minHeight="40dp"
android:initialLayout="@layout/my_widget_layout">
</appwidget-provider>

So, put this code in a file named my_widget_info.xml in the folder <MyProject>\res\xml\. Here we set minWidth and minHeight properties to 40dp so that our widget will occupy a single square place in the Home Screen. Then we define the layout we want to use in order to draw it by setting the initialLayout attribute. We will see more about the layout later.

UpdatePeriodMillis Attribute

We will not use the updatePeriodMillis attribute in this article but it is really important to give you the heads up and explain a few things about it. This attribute defines the update period of our widget. This means that we are telling the platform how often to call our code to update our widget. By doing so the platform wakes the device even if it is in sleep mode (screen is off) to update our widget and also the entire Home Screen. So we need to be really careful not drain the device's battery while using this attribute. It is so important that even AOSP, from the early version of 1.6 and on, ignores any value of this attribute that is lower than 30 minutes!>
In case you think it is crucial for your widget to be updated more frequently, although discouraged, you'll have to use AOSP Services to do your job.

Preview Image

The "Choose Widget" screen is shown when the user wants to add a new widget in the Home Screen. In this screen all the available widgets are show cased. Here is our opportunity to show the user how awesome our widget is and convince him to add it to his Home Screen. We do that by using a single image which should let the user see what the widget would look like. So the image must show the truth and be as "descriptive" as possible.

Tip.pngTip: A picture is worth a thousand words, so make it count!

So, adding the previewImage attribute in our "my_widget_info.xml" file will look like

android:previewImage="@drawable/previewImage"

Layout

Our purpose is to make the widget useful to the user by showing the number of notes created and the number of those that are important. We will also try to make the widget animate so that it reminds a bit of the Live Tiles we see on Lumia. To do so we will rely our layout on a ViewFlipper. So let's create a file named my_widget_layout.xml, put it in the project's \res\layout\ folder and place the below code inside it.

<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:id="@+id/RelativeLayout1"
android:layout_width="wrap_content"
android:layout_height="wrap_content" >
 
<ViewFlipper
android:id="@+id/viewFlipper1"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:layout_centerHorizontal="true"
android:layout_centerVertical="true"
android:inAnimation="@anim/in_from_above"
android:outAnimation="@anim/stay" >
 
<RelativeLayout
android:layout_width="match_parent"
android:layout_height="match_parent" >
 
<ImageView
android:id="@+id/widget_vf1_back"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_centerHorizontal="true"
android:layout_centerVertical="true"
android:scaleType="fitCenter"
android:src="@drawable/vf1a" />
 
<TextView
android:id="@+id/widget_vf1_text"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_alignParentBottom="true"
android:layout_alignParentLeft="true"
android:layout_marginBottom="2dp"
android:layout_marginLeft="2dp"
android:text="@string/app_name"
android:textAppearance="?android:attr/textAppearanceMedium"
android:textColor="#fff"
android:textSize="16sp" />
 
<RelativeLayout
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_alignParentRight="true"
android:layout_alignParentTop="true"
android:layout_marginRight="2dp"
android:layout_marginTop="2dp" >
 
<ImageView
android:id="@+id/imageView1"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_centerHorizontal="true"
android:layout_centerVertical="true"
android:adjustViewBounds="true"
android:maxHeight="29dp"
android:maxWidth="29dp"
android:scaleType="fitXY"
android:src="@drawable/vf1_circle" />
 
<TextView
android:id="@+id/widget_badge"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_centerHorizontal="true"
android:layout_centerVertical="true"
android:text="20"
android:textSize="15sp"
android:textColor="#fff" />
</RelativeLayout>
</RelativeLayout>
 
<RelativeLayout
android:layout_width="match_parent"
android:layout_height="match_parent"
android:background="#104194" >
 
<TextView
android:id="@+id/widget_sumtext"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_alignParentBottom="true"
android:layout_alignParentLeft="true"
android:layout_marginBottom="2dp"
android:layout_marginLeft="2dp"
android:text="Medium Text"
android:textSize="14sp"
android:textColor="#fff" />
</RelativeLayout>
 
</ViewFlipper>
 
</RelativeLayout>

As you can see we have a ViewFlipper and two RelativeLayouts as its child views. There are a couple of things we should notice here. First, we have named some of the views with the android:id attribute so that we can find them from our code. Second, we'll use the inAnimation and outAnimation attributes in order to "flip" the views of the ViewFlipper.

We want to achieve this animation below when the user taps on the widget.

One view is coming from above and the other just stays at its place. Here is how to do it. Create an XML file named in_from_above.xml to the project's \res\anim\ folder and place the code below in it.

<set xmlns:android="http://schemas.android.com/apk/res/android"
android:shareInterpolator="false">
<translate
android:fromXDelta="0%" android:toXDelta="0%"
android:fromYDelta="-100%" android:toYDelta="0%"
android:duration="400"
android:interpolator="@android:anim/accelerate_decelerate_interpolator"/>
</set>

Do the same for the file stay.xml with this code.

<set xmlns:android="http://schemas.android.com/apk/res/android"
android:shareInterpolator="false">
<translate
android:fromXDelta="0%" android:toXDelta="0%"
android:fromYDelta="0%" android:toYDelta="0%"
android:duration="400" />
</set>

With that our widget's UI is ready. Let's write now some code to update its views with the appropriate values.

AppWidgetProvider

In order to capture the user's and the platform's interaction with our widget we need to extend AppWidgetProvider. We will create a class named MyWidgetProvider in our project and implement two methods in it, onUpdate and onReceive. The onUpdate method is called either when the user adds the widget in the Home Screen in order to make the initial setup or when the time to update the widget has come as this is defined with the updatePeriodMillis attribute.

Taking it a step further

This article doesn't cover App Widget configuration activities. That king of Activity is optional for a widget. It is the Activity launched when the user adds the widget in the Home Screen in order to modify its settings.

References

Android API Guide: App Widgets https://developer.android.com/guide/topics/appwidgets/index.html

390 page views in the last 30 days.
×