Homescreen Widgets Demystified

1. Homescreen WidgetsDemystified Pearl Chen @androidsNsheep AndroidTO // Oct 26, 2010

2. Hi, I'm a web developer... So many ways to create an Android application… but none of them create homescreen widgets!

3. ...and I ♥ homescreen widgets Examples default Donut homescreen default Froyohomescreen

4. ...and I ♥ homescreen widgets Examples Gmail Unread Count HTC SenseUI email widget

5. ...and I ♥ homescreen widgets Examples Music Players Settings controls

6. Key reasons to build a widget • At-a-glance information • unread messages, calendar items, to do lists • Control apps that run in the background • Music player • Toggle settings • settings that affect other applications such as GPS or wifi • Consider how the Google Voice widget can toggle between “Use for all calls”, “Do not use for calls”, “International calls only”, and “Ask for every call”. You might want to toggle this setting before opening the Dailer app • “Smart” shortcuts • Reduce something that would normally take at least 2 steps into 1 • If it simply opens another application, keep it as a regular application shortcut

7. (Another) key reason to build a widget Keep users engaged with your app! out of sight == out of mind  Hey! Don’t forget about me!

8. Designing Widgets Widget Design Best Practices UI Guidelines developer.android.com/guide/practices/ui_guidelines/widget_design.html

9. Designing Widgets Lighter color themein Cupcake and Donut Darker color themein Éclair and Froyo

10. Coding Widgets App Widgets Framework Guide developer.android.com/guide/topics/appwidgets/index.html

11. Sample Widget Code • Download • Import into Eclipse as an ‘Existing Project’ • Run code.google.com/p/androidto-basicwidget/

12. Overview of Widget Development • Create a new Android project in Eclipse without an Activity class • Declare AppWidgetProviderInfo object • Create xml layout file for widget view • Extend the AppWidgetProvider class • Update AndroidManifest.xml

13. Overview of Widget Development • Create a new Android project in Eclipse without an Activity class • Declare AppWidgetProviderInfo object • Create xml layout file for widget view • Extend the AppWidgetProvider class • Update AndroidManifest.xml

14. Create a new Android project Widgets not available in Android 1.1 No need for an Activity unless there’s going to be a standalone application

15. Overview of Widget Development • Create a new Android project in Eclipse without an Activity class • Declare AppWidgetProviderInfo object • Create xml layout file for widget view • Extend the AppWidgetProvider class • Update AndroidManifest.xml

16. AppWidgetProviderInfo • Create an xml folder in the res folder. • In the xml folder, create a new Android XML File

17. Because the Home screen's layout orientation (and thus, the cell sizes) can change, as a rule of thumb, you should assume the worst-case cell size of 74 pixels for the height and width of a cell. However, you must subtract 2 from the final dimension to account for any integer rounding errors that occur in the pixel count. To find your minimum width and height in density-independent pixels (dp), use this formula:(number of cells * 74) - 2Following this formula, you should use 72 dp for a height of one cell, 294 dp and for a width of four cells. AppWidgetProviderInfo <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"android:minWidth="294dp"android:minHeight="72dp"android:updatePeriodMillis=“30000"android:initialLayout="@layout/widget"></appwidget-provider> (number of cells * 74) - 2

18. Overview of Widget Development • Create a new Android project in Eclipse without an Activity class • Declare AppWidgetProviderInfo object • Create xml layout file for widget view • Extend the AppWidgetProvider class • Update AndroidManifest.xml

19. XML Layout File • There’s already a main.xml file in the res/layout folder so just reuse that.

20. XML Layout File • I renamed it to widget.xml so it was more descriptive. • Added a background and padding to the container. • And gave the TextView an id of current_time.

21. XML Layout File • And let’s also add a refresh button as a ImageButtonwith and id of refresh.

22. If a widget is not an Activity, what is it? An Activitycould simply be described as an UI screen.

23. If a widget is not an Activity, what is it? An Activitycould simply be described as an UI screen. It contains Viewwidgets such as LinearLayout, TextView, and Button typically marked up in a layout xml file.

24. If a widget is not an Activity, what is it? An Activitycould simply be described as an UI screen. It contains Viewwidgets such as LinearLayout, TextView, and Button typically marked up in a layout xml file. e.g. Button btn = (Button) findViewById(R.id.my_button); btn.setText(“Submit”);

25. If a widget is not an Activity, what is it? Widgets also contain Viewwidgets such as LinearLayout, TextView, and Button(but there are limitations to what Views you can use).

26. If a widget is not an Activity, what is it? Button btn = (Button) findViewById(R.id.my_button); btn.setText(“Submit”);

27. If a widget is not an Activity, what is it? RemoteViews RemoteViewsremoteView = new RemoteViews( context.getPackageName(), R.layout.widget ); remoteView.setTextViewText( R.id.my_button, “Submit” );

28. If a widget is not an Activity, what is it? RemoteViews The application component that supplies the UI for a widget is a BroadcastReceiver

29. Overview of Widget Development • Create a new Android project in Eclipse without an Activity class • Declare AppWidgetProviderInfo object • Create xml layout file for widget view • Extend the AppWidgetProvider class • Update AndroidManifest.xml

30. AppWidgetProvider public class BasicWidgetProviderextendsAppWidgetProvider{ @Override public void onUpdate( Context context, AppWidgetManagerappWidgetManager, int[] appWidgetIds) { super.onUpdate( context, appWidgetManager, appWidgetIds ); //do some stuff every updatePeroidMillis! } }

31. AppWidgetProvider void onUpdate( Context context, AppWidgetManagerappWidgetManager, int[] appWidgetIds ) void onEnabled( Context context ) void onDeleted( Context context, int[] appWidgetIds ) void onDisabled( Context context ) void onReceive( Context context, Intent intent )

32. AppWidgetProvider public void onUpdate( Context context, AppWidgetManagerAppWidgetManager, int[] appWidgetIds) { /* update each widget that belongs to this provider individually by setting an alarm because we're setting an alarm, onUpdate is really only called when a new widget is added, or the phone restarts */ final int N = appWidgetIds.length; for (int i=0; i<N; i++) { intappWidgetId = appWidgetIds[i]; setAlarm(context, appWidgetId, 30000); } }

33. AppWidgetProvider public static void setAlarm(Context context, intappWidgetId, intupdateRate) { // To prevent any ANR timeouts, // we perform the update in an intent service PendingIntentpendingIntent= createUpdatePendingIntent(context,REFRESH,appWidgetId); AlarmManageralarms = (AlarmManager) context.getSystemService(Context.ALARM_SERVICE); //and then have the alarm wake up the system to do updates alarms.setRepeating(AlarmManager.ELAPSED_REALTIME, SystemClock.elapsedRealtime(), updateRate, pendingIntent); }

34. AppWidgetProvider public static class UpdateServiceextends IntentService{ @Override public void onHandleIntent(Intent intent) { ComponentNamewidget = new ComponentName( this, BasicWidgetProvider.class); AppWidgetManagerappWidgetManager = AppWidgetManager.getInstance(this); appWidgetManager.updateAppWidget(widget, buildUpdate(this, intent)); } private RemoteViewsbuildUpdate(Context context, Intent intent) { RemoteViewsviews = new RemoteViews( context.getPackageName(), R.layout.widget ); //update the UI here… return views; } } context.startService(new Intent(context, UpdateService.class));

35. Overview of Widget Development • Create a new Android project in Eclipse without an Activity class • Declare AppWidgetProviderInfo object • Create xml layout file for widget view • Extend the AppWidgetProvider class • Update AndroidManifest.xml

36. AndroidManifest.xml <receiver android:name="BasicWidgetProvider" > <intent-filter> <action android:name="android.appwidget.action.APPWIDGET_UPDATE" /> <action android:name="android.appwidget.action.APPWIDGET_ENABLED" /> <action android:name="android.appwidget.action.APPWIDGET_DISABLED" /> <action android:name="android.appwidget.action.APPWIDGET_DELETED" /> </intent-filter> <meta-data android:name="android.appwidget.provider" android:resource="@xml/basic_provider_info" /> </receiver> <service android:name=".BasicWidgetProvider$UpdateService" />

37. THANK YOU! Pearl Chen @androidsNsheep