Part -1: Creating a Simple App Widget with Configuration Actvitiy


This app widget tutorial is with respect to the app widget present in Nepal Khabar present in the Google play store.
While writing this tutorial, it is presumed that the readers will have basic knowledge about how to create and run a basic project in android and have some knowledge of java and xml file.

What is an app widget?

Technically, an app widget is a miniature application.In simple terms, the applications we see running on the home screen is app widget. These apps are in homescreen to show periodic updates of the data. These data must be helpful to the users.These app widgets are in the homescreen due to AppWidgetProvider.

What are the basic things to know about, when creating an app widget in your application?

So that you can easily create one app widget of your choice, i want to give a little bit of concept on the basics of app widget. I have listed out the required classes and xml file to create an app widget. So, go ahead, read it and create an app widget of your choice.

First off all, know what AppWidgetProvider is…….

AppWidgetProvider publishes app widget in the homescreen. It publishes app widget by allowing us (i.e. developers ) to interface with the app widget programmatically, based on broadcast events.It provides the broadcast when the App Widget is updated, enabled, disabled and deleted. It is defined in manifest as shown in the given snippet of code :

 <receiver android:name="ExampleAppWidgetProvider" >  
   <intent-filter>  
     <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />  
   </intent-filter>  
   <meta-data android:name="android.appwidget.provider"  
         android:resource="@xml/example_appwidget_info" />  
 </receiver>  

<action android:name =”android.appwidget.action.APPWIDGET_UPDATE” /> is responsible for updating the app widget.

android:name within meta-date specifies the metadata name. Use android.appwidget.provider to identify the data as the AppWidgetProviderInfo descriptor.

android:resource within meta-data defines the layout for the app widget,its update frequency. It is our AppWidgetProviderInfo file.

1. AppWidgetProviderInfo 

AppWidgetProvider must have the knowledge about the layout of the app widget, the update frequency of the app widget and it must also know whether any configuration activity( optional ) for app widget is defined. These informations are provided to the AppWidgetProvider through AppWidgetProviderInfo. The AppWidgetProviderInfo is xml file. It must be located inside res>xml folder. It is defined within android:resource in the receiver tag of manifest file. The AppWidgetProviderInfo xml file generally consist of the following attributes as shown in the given snippet of code :

 <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"  
   android:configure="ConfigurationActivity"  
   android:initialLayout="@layout/layout_appwidget_large"  
   android:minHeight="115dp"  
   android:minWidth="250dp"  
   android:updatePeriodMillis="21600000" ><!-- 6hrs -->  
 </appwidget-provider>  

2. The app widget layout:

An app widget is different from normal Activity in Android. It runs on the home screen and there may be other app widgets running that we cannot interfere with. We must understand the difference between normal Activity and app widget. A normal Activity individual controls can draw outside of their own bounds, and even those of their parent layouts if they allow it via their clipChildren attribute. However doing this on the home screen could interfere with other widgets, and to prevent this kind of bad behaviour from app widgets, they do not get direct access to the app widget layout and it’s child views.

Instead they must use a RemoteViews object to update these views. RemoteViews is a proxy which provides us with limited access to these views, and consequently we have a limited subset of widgets that we can use in our app widget layouts such as AnalogClock, Button, Chronometer, ImageButton, ImageView, ProgressBar, TextView, ViewFlipper, ListView, GridView, StackView, AdapterViewFlipper. We are also limited to the following layout types: FrameLayout, LinearLayout, RelativeLayout, GridLayout

3. AppWidgetConfiguration Activity:

AppWidgetConfiguration Activity is an optional Activity that launches when the user adds our App Widget and allows him or her to modify App Widget settings at create-time.To transform an activity to a configuration one, we must provide <action android:name =”android.appwidget.action.APPWIDGET_UPDATE”> within <intent-filter> tag while defining it in manifest file.We must also include it in the appwidget provider info file as shown in the given code snippet

 <!-- app widget configuration activity in manifest -->  
     <activity android:name="ConfigurationActivity" >  
       <intent-filter>  
            <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE" />  
       </intent-filter>  
     </activity>  

Configuration Activity, is like any Activity, with two exceptions.

  • In onCreate() we have to ensure that if the user presses BACK or cancelled the activity, then we should not add app widget. This is done by adding
 setResult(RESULT_CANCELED);  
  • The result should include the App Widget ID passed by the Intent that launched the Activity(saved in the Intent extras as EXTRA_APPWIDGET_ID).
 private void initializeAppWidget(){  
      mAppWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;  
           Intent intent = getIntent();  
           Bundle extras = intent.getExtras();  
           if (extras != null) {  
                mAppWidgetId = extras.getInt(EXTRA_APPWIDGET_ID,  
                          INVALID_APPWIDGET_ID);  
                showProgressDialog();  
                saveTheUserValueInPref(selectedCategory, sourceAndLanguage,  
                          mAppWidgetId);  
                getDataToLoadInWidget = new GetDataToLoadInWidget(  
                          ConfigurationActivity.this, selectedSource,  
                          selectedLanguage, selectedCategory);  
           }  
           if (mAppWidgetId == INVALID_APPWIDGET_ID) {  
                finish();  
           }  
           }  

Then, when you have finished configuration, return the app widget id:

   private void configureYourResult(){  

           //configure your activity   
           //after successful do as  

          Intent resultValue = new Intent();  
           resultValue.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, mAppWidgetId);  
           setResult(RESULT_OK, resultValue);  
           finish();  
      }  

4. The AppWidgetProvider class :The AppWidgetProvider receives only the event broadcasts that are relevant to the App Widget, such as when the App Widget is updated, deleted, enabled, and disabled. When we fire an android.appwidget.action.APPWIDGET_UPDATE from ConfigurationActivity. 

 public class CopyOfWidgetProviderLarge extends AppWidgetProvider {  
      Context context;  
      public void onUpdate(Context context, AppWidgetManager appWidgetManager,  
                int[] appWidgetIds) {  
           this.context = context;  
           Log.d("onUpdate", "called");  
           for (int widgetId : appWidgetIds) {  
                updateAppWidget(context, appWidgetManager, widgetId);  
           }  
      }  

      private void updateAppWidget(Context context,  
                AppWidgetManager appWidgetManager, int appWidgetId) {  
           // Inflate layout.  
           RemoteViews remoteViews = new RemoteViews(context.getPackageName(),  
                     R.layout.widget);  
           // Update UI.  
           remoteViews.setTextViewText(R.id.label, "testing");  
           appWidgetManager.updateAppWidget(appWidgetId, views);  
      }  
 }  

The sample project is located in github. In the next tutorial, I am going to write about Multiple Sized Widdget. Until then, Happy Coding 😀

References:

Styling Android
Malubu WordPress
Android Developer Site

 

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s