2014-09-09 – This has been updated, see below.

Having recently written my first Widget for Android, here are some of the things I learned in the process.

Use a thread, not just a service

In the blog post introducing the AppWidget framework, you are encouraged to use a service to perform your widget updates if you are doing anything that might take a little longer, in order to avoid Application Not Responding (ANR) timeouts. However, this will usually not be enough. Since your service callbacks also run in your application’s main thread, you’ll still going to trigger ANRs if you do work there. Services really just declarative components, metadata that tell the system “I would appreciate if you wouldn’t kill me”.

The solution is to have your service start a separate thread. For an example, see Jeffrey Sharkey’s android-sky Widget.

Stop your service when you’re done

When your done with updating (if your using a thread, it’ll be when your thread has finished), make sure you stop your service. Nobody seems to be doing this, including the example code in the official blog post, nor sample projects by Android team members. As a result, so many widgets have their process run in the background all the time, not allowing Android to kill it to reclaim memory. Considering that RAM isn’t exactly a plentiful resource on devices like the G1, I would have thought this were especially important. Unless your updating multiple times an hour, I would strongly suggest that stopping your service and letting Android free up your process when necessary is the right thing to do.

Try to work around the bugs in Android 1.5 and the Launcher’s Widget implementation

It turns out there are quite a few of them, and they all seem to revolve around issues with deleting a widget. In particular:

• AppWidgetProvider fails to handle delete intents correctly. As a result, if you are subclassing it, your onDelete() method will not be called. The solution is to override onReceive() and handling delete intents yourself. Here’s a code snippet.
• In any case, if a user deletes an instance of your widget, the 1.5 default home screen will still keep sending update requests for the already deleted widget’s id, until the user adds a new instance of your widget (apparently, some internal bundle of widget ids is not reset on delete). This seems like this could result in a considerable waste of resources, or even impact your functionality, with you sending out widget updates that nobody is going to see. Note: I’m not sure if those obsolete widget ids are cleared out on reboot (probably). You might also not have this problem if you’re using custom scheduling instead of the default update facility.
  The best one can do here appears to be keeping an internal list of deleted widgets (widgets for which you – hopefully – received a delete intent), and then just skipping those updates.
• Finally, there seems to be another issue with phantom widgets when a configure activity is used and the user cancels it. In this case also, you’ll continue to receive updates for the widget (which won’t be shown anywhere), except it seems even worse, because apparently this time around, widget will really exist internally, rather than just some internal state not being update correctly (so even a reboot won’t help here).
  The work around seems similar: keep information around that indicates whether a widget as been configured successfully, and don’t bother updating widgets that haven’t.

2009-07-18: It appears there is another widget bug.

2014-09-09 – The 5 year update.

In my experience, this has all been fixed, with one small note.

• AppWidgetProvider.onDeleted is called correctly, no workaround necessary. Simply compile against any remotely recent Android SDK, you’ll be fine.
• People still complain about phantom widgets, but I cannot confirm this. I do not get any update requests from the system for widgets that have been deleted.

Here is what I know about phantom widgets.

AppWidgetProvider.onUpdate is called before the widget is configured

The documentation to this day claims that this is not so (“the system will not send the ACTION_APPWIDGET_UPDATE broadcast when a configuration Activity is launched“), but at least on my Sony Xperia with Android 4.4, this is not the case. Admittedly, Sony is using a custom home screen. At least you cannot rely on this, then.

The solution is simple though: Simply ignore that first update, that the docs claim shouldn’t be sent. Note whether a particular app widget id has been configured, then only process updates for widgets that have been configured.

When the user cancels the configuration activity, AppWidgetProvider.onDelete is called.

If you chose not to ignore that first update, that was sent before your widget’s configuration activity completed, you will get the onDelete callback once the configuration activity is canceled. Just be sure to set the RESULT_CANCELED return intent. Do this in onCreate, and then simply override the result value it when the user completes the configuration. This is much more simpler and more reliable than trying to cancel in onBackPress or onStop or onPause.

With the RESULT_CANCELLED value properly returned, I reliably receive onDelete callbacks, whether I exit the configuration activity via BACK or HOME.

If you use your own scheduler, you will still receive those events!

This was throwing me off first, but since I’m scheduling my own widget updates using AlarmManager, any such alarm already scheduled will still be delivered, even after the user has deleted your widget. To Android, your custom alarms have nothing to do with the widget, after all.

So you’ll either have to cancel those alarms, or, which is what I do, if only for historical reasons due to the bugs that existed five years ago, I mark the widget as deleted when it is removed, and subsequently ignore everything coming in for deleted widget ids.