Namespaces

Variants
Actions

Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries over the next few weeks. Thanks for all your past and future contributions.

(Difference between revisions)

Creating widgets for your Nokia X platform applications

From Wiki
Jump to: navigation, search
spiretos (Talk | contribs)
(Spiretos -)
 
spiretos (Talk | contribs)
(Spiretos -)
Line 1: Line 1:
[[Category:Draft]]
+
[[Category:Draft]][[Category:Nokia X]][[Category:Tutorial]]
 
{{Abstract|This article shows how to create widgets for your Nokia X platform applications.}}
 
{{Abstract|This article shows how to create widgets for your Nokia X platform applications.}}
  
''Enter article metadata as described below. Note that this template can be placed anywhere in the article. Do not remove parameters that you do not use''
 
 
{{ArticleMetaData <!-- v1.3 -->
 
{{ArticleMetaData <!-- v1.3 -->
 
|sourcecode= <!-- Link to example source code e.g. [[Media:The Code Example ZIP.zip]] -->
 
|sourcecode= <!-- Link to example source code e.g. [[Media:The Code Example ZIP.zip]] -->
Line 23: Line 22:
 
}}
 
}}
  
 +
{{Note|This is an entry in the [[Nokia X Wiki Challenge 2014Q1]]}}
  
 
== Introduction ==
 
== 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 of the application.
+
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.
 
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.
Line 31: Line 31:
  
 
== Building blocks of a Widget ==
 
== Building blocks of a Widget ==
We need three thing in order to create an App Widget.
+
We need three things in order to create an App Widget.
 
* AppWidgetProviderInfo
 
* AppWidgetProviderInfo
 
An xml file where we define metadata for the widget.
 
An xml file where we define metadata for the widget.
Line 39: Line 39:
 
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.
 
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.
+
Let's see them one by one.
 +
 
 
== AppWidgetProviderInfo ==
 
== 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.
+
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.
 
<code xml>
 
<code xml>
 
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
 
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
Line 48: Line 49:
 
     android:initialLayout="@layout/my_widget_layout">
 
     android:initialLayout="@layout/my_widget_layout">
 
</appwidget-provider>
 
</appwidget-provider>
</code>
+
</code><br />
So, put this code in a file named “my_widget_info.xml” in the folder <MyProject>\res\xml\.
+
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 {{Icode|40dp}} so that our widget will occupy a single square place in the Home Screen.
+
Here we set ''minWidth'' and ''minHeight'' properties to {{Icode|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.
+
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.
{{Tip|{{Icode|updatePeriodMillis}}
+
 
<br/>We will not use this attribute in this article but it is really important to give you the heads up and explain a few things about it. The “updatePeriodMillis” 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 so 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! But, in case you thing it is crucial for your widget to be updated more frequently, although discouraged, you’ll have to use AOSP Services (http://developer.android.com/guide/components/services.html) to do your job.}}
+
== UpdatePeriodMillis Attribute ==
 +
We will not use the {{Icode|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!><br />
 +
In case you think it is crucial for your widget to be updated more frequently, although discouraged, you'll have to use [http://developer.android.com/guide/components/services.html AOSP Services] to do your job.
 
== Preview Image ==
 
== 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.
+
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| A picture is worth a thousand words , so make it count!}}
+
{{Tip| 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
+
So, adding the previewImage attribute in our "my_widget_info.xml" file will look like
 
<code xml>
 
<code xml>
 
android:previewImage="@drawable/previewImage"
 
android:previewImage="@drawable/previewImage"
</code>
+
</code><br />
  
 
== Layout ==
 
== Layout ==
Our purpose is to make the widget useful to the user be 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.
+
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.
+
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.
 
<code xml>
 
<code xml>
 
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
 
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
Line 160: Line 163:
  
 
</RelativeLayout>
 
</RelativeLayout>
</code>
+
</code><br />
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.
+
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 {{Icode|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.
 
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.
 
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.
+
Create an XML file named ''in_from_above.xml'' to the project's \res\anim\ folder and place the code below in it.
 
<code xml>
 
<code xml>
 
<set xmlns:android="http://schemas.android.com/apk/res/android"
 
<set xmlns:android="http://schemas.android.com/apk/res/android"
Line 176: Line 179:
 
           android:interpolator="@android:anim/accelerate_decelerate_interpolator"/>
 
           android:interpolator="@android:anim/accelerate_decelerate_interpolator"/>
 
</set>
 
</set>
</code>
+
</code><br />
Do the same for the file “stay.xml” with this code.
+
Do the same for the file ''stay.xml'' with this code.
 
<code xml>
 
<code xml>
 
<set xmlns:android="http://schemas.android.com/apk/res/android"
 
<set xmlns:android="http://schemas.android.com/apk/res/android"
Line 186: Line 189:
 
           android:duration="400" />
 
           android:duration="400" />
 
</set>
 
</set>
</code>
+
</code><br />
With that our widget’s UI is ready. Let’s now write some code to update its views with the appropriate values.
+
With that our widget's UI is ready. Let's write now some code to update its views with the appropriate values.
 
== AppWidgetProvider ==
 
== 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.
+
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.
 
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 ==
 
== Taking it a step further ==
This article doesn’t cover App Widget configuration activities. That king of {{Icode|Activity}} is optional for a widget. It is the {{Icode|Activity}} launched when the user adds the widget in the Home Screen in order to modify its settings.
+
This article doesn't cover App Widget configuration activities. That king of {{Icode|Activity}} is optional for a widget. It is the {{Icode|Activity}} launched when the user adds the widget in the Home Screen in order to modify its settings.
  
 
== References ==
 
== References ==
 
Android API Guide: App Widgets https://developer.android.com/guide/topics/appwidgets/index.html
 
Android API Guide: App Widgets https://developer.android.com/guide/topics/appwidgets/index.html

Revision as of 21:16, 14 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 (14 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

442 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×