{"id":1873,"date":"2013-10-13T09:10:46","date_gmt":"2013-10-12T21:10:46","guid":{"rendered":"https:\/\/www.deltics.co.nz\/blog\/?p=1873"},"modified":"2013-10-14T08:48:16","modified_gmt":"2013-10-13T20:48:16","slug":"developing-an-appwidget-part-5","status":"publish","type":"post","link":"https:\/\/www.deltics.co.nz\/blog\/posts\/1873\/","title":{"rendered":"Developing an AppWidget – Part 5"},"content":{"rendered":"[Estimated Reading Time: <\/span> 7<\/span> minutes]<\/span><\/span>

In my previous post<\/a> I explained how I believed I had solved a problem with my widget, only to discover that it created a different problem in the process.<\/p>\n

I had believed that IntentService based services were long-lived, but in fact this is not the case. However, the change remains valid for solving the problem of my update alarm surviving device sleep, leaving only the question of how to refactor the behaviour that using an IntentService<\/strong> had broken.<\/p>\n

<\/p>\n

Devices Playing Possum<\/h2>\n

When an Android device turns off the screen, this does not necessarily mean that the device is yet asleep. Any application or widget that continues to update itself when the screen is off is pretty much wasting it’s time but more importantly is wasting precious battery as well.<\/p>\n

Fortunately there are notifications we can receive that will allow us to adjust our behaviour when the screen goes off (and comes back on) which means we can be even more efficient in our battery use.<\/p>\n

Yet More Intents<\/h3>\n

As you may have come to expect by now, this involves Intent<\/strong>s. Again.<\/p>\n

In this case we are interested in a pair of system defined intents:<\/p>\n

    \n
  • Intent.ACTION_SCREEN_OFF<\/li>\n
  • Intent.ACTION_SCREEN_ON<\/li>\n<\/ul>\n

    Unlike the battery level information, these intents are not “sticky”. They are dynamic intents, broadcast to interested parties as and when the screen is turned on or off, whether by the system in response to a time-out, or by the user specifically.<\/p>\n

    These particular system intents are a bit unusual however.<\/p>\n

    Normally we would add an intent-filter<\/code> to our manifest to register our interest in receiving intents and identifying the entity (or entities) in our application that will respond to them. But these intents specifically cannot<\/em> be declared in this way. Or rather, you can declare them but they won’t be acknowledged by the system. You won’t receive the intents.<\/p>\n

    Instead we must create and register a receiver at runtime.<\/p>\n

    Originally, I chose to create and register my receiver in the onHandleIntent<\/code> method of my UpdateService<\/code>. This was the mistake I made. I had believed that my UpdateService was “long-lived” when it wasn’t. However, deriving from IntentService did address my issue with surviving sleep.<\/p>\n

    So, for my screen state notifications all I needed to do was create an entirely new service that is<\/em><\/strong> long-lived.<\/p>\n

    \r\n\r\ninterface\r\n\r\n  ScreenStateService = public class (Service)\r\n  private\r\n    class var cfScreenStateReceiver: ScreenStateReceiver;\r\n  public\r\n    method onDestroy; override;\r\n    method onBind(aIntent: Intent): IBinder; override;\r\n    method onStartCommand(aIntent: Intent; aFlags, aStartID: Integer): Integer; override;\r\nend;\r\n\r\n<\/pre>\n
    As before my service class overrides onBind<\/code> to provide a default implementation returning NIL<\/strong>.<\/p>\n
    My onStartCommand<\/code> override creates and registers the receiver of the SCREEN_ON<\/code>\/SCREEN_OFF<\/code> intents.<\/p>\n
    My onDestroy<\/code> override unregisters the receiver.<\/p>\n
    The cfScreenStateReceiver<\/strong> class var holds a reference to my registered receiver for as long as it remains registered.<\/p>\n
    \r\n\r\nimplementation\r\n\r\n  method ScreenStateService.onDestroy;\r\n  begin\r\n    unregisterReceiver(fScreenStateReceiver);\r\n    fScreenStateReceiver := NIL;\r\n\r\n    inherited;\r\n  end;\r\n\r\n\r\n  method ScreenStateService.onStartCommand(aIntent: Intent; \r\n                                           aFlags: Integer; \r\n                                           aStartID: Integer): Integer;\r\n  begin\r\n    if NOT assigned(fScreenStateReceiver) then\r\n    begin\r\n      var screenState  := new IntentFilter;\r\n      \r\n      screenState.addAction(Intent.ACTION_SCREEN_ON);\r\n      screenState.addAction(Intent.ACTION_SCREEN_OFF);\r\n\r\n      fScreenStateReceiver := new ScreenStateReceiver;\r\n      registerReceiver(fScreenStateReceiver, screenState);\r\n    end;\r\n\r\n    result := START_STICKY;\r\n  end;\r\n<\/pre>\n
    Creating the receiver is simple enough, as is registering it using the registerReceiver<\/code> method, though this time we pass a reference to the receiver to be received, rather than NIL<\/strong>, as we did with the battery information “sticky” intent.<\/p>\n
    We also pass in the IntentFilter<\/strong> identifying the intents this receiver should receive.  This also is relatively straightforward.  We simply create the new filter and add the actions of interest to it.<\/p>\n
    The key to making the service long-lived is to return Service.START_STICKY<\/strong> from this method.<\/p>\n
    Live Long, and Prosper<\/del> If You Have Lots To Process<\/h3>\n
    This code was originally implemented in my existing UpdateService<\/strong>, and (with the addition of calls to Android Log methods) I found that my UpdateService<\/strong> would register the ScreenStateReceiver<\/strong> but was then immediately destroyed and thus immediately UNregister<\/strong> that receiver.  This was how I learned that the notion that an IntentService<\/strong> is long-lived was wrong.<\/p>\n
    With an IntentService<\/strong> you don’t get to decide what is returned from onStartCommand<\/code> since the extension point is onHandleIntent<\/code>, with no mechanism for indicating any preferred service lifetime.<\/p>\n
    So where did I get the idea that IntentService was appropriate for long-lived services ?<\/p>\n
    The key is in distinguishing between a stated service lifetime which may determine how the service is managed after it completes processing<\/em>, and the amount of time required to perform that processing itself<\/em>.<\/p>\n
    The real<\/em> point of IntentService<\/strong> is that onHandleIntent<\/code> is called by a worker thread, and thus will not block your application main thread.  Thus, if you have a service which will be doing a potentially significant amount of work when handling an intent, an IntentService<\/strong> is a convenient way of shunting that work into a worker thread.<\/p>\n
    But once the work is done (onHandleIntent<\/strong> returns) the service will be quickly cleaned up.<\/p>\n
    In other words, if you have a potentially long living service, an IntentService<\/strong> based implementation is highly recommended<\/em>.  But using an IntentService<\/strong> does not itself make a service long lived.<\/p>\n
    In any event, I now have a suitable service which will register a receiver for the intents of interest.  The question now is what to do when we receive these intents, and this is of course determined by how I implement the ScreenStateReceiver<\/strong> class itself.<\/p>\n
    Receiving Intents, Load and Clear<\/h3>\n
    First of all, declaring the ScreenStateReceiver<\/strong> is trivial.  It is a sub-class of BroadcastReceiver<\/strong>, and I only need to override one method, onReceive<\/code>:<\/p>\n
    \r\n\r\ninterface\r\n\r\n  uses\r\n    android.app,\r\n    android.content;\r\n    \r\n\r\n  type\r\n    ScreenStateReceiver = public class(BroadcastReceiver)\r\n    public\r\n      method onReceive(aContext: Context; aIntent: Intent); override;\r\n    end;\r\n\r\n<\/pre>\n
    The question is:  What should I do when the screen comes on or goes off ?<\/em><\/p>\n
    What I want to do is enable or disable my update alarm as appropriate.  If the screen goes off, I want to stop updating my widget, and when the screen comes on resume those updates.<\/p>\n
    But the code for doing this is in my widget provider.  I could perhaps duplicate the scheduling and cancellation of the alarm and in this simple case such duplication might be acceptable.  I could perhaps refactor the code into class methods on the widget provider class which I can call directly from my ScreenStateReceiver<\/strong>.  But this feels wrong for some reason (I honestly do not know if it is)<\/p>\n
    What I would prefer to do is ensure that the communication between my ScreenStateReceiver<\/strong> and the widget provider follows normal Android protocols and that means intents.  This time, sending<\/em> an intent.<\/p>\n
    I cannot send the system defined ACTION_SCREEN_ON<\/strong>\/OFF<\/strong> intents themselves.  Android system will not allow that with these particular intents.<\/p>\n
    But I can send a custom intent and with an intent-filter<\/code> in my manifest I can ensure that my BatteryWidgetProvider<\/strong> will be signalled.<\/p>\n
    So first, a couple of class constants for the intent names, to avoid silly typing mistakes:<\/p>\n
    \r\n    ScreenStateReceiver = public class(BroadcastReceiver)\r\n    public\r\n      const SCREEN_ON  = 'nz.co.deltics.SCREEN_ON';\r\n      const SCREEN_OFF = 'nz.co.deltics.SCREEN_OFF';\r\n      ...\r\n    end;\r\n<\/pre>\n
    And now to receive the system screen state intents and pass them on to the widget provider in the form of my corresponding custom intents:<\/p>\n
    \r\n  method ScreenStateReceiver.onReceive(aContext: Context; aIntent: Intent);\r\n  begin\r\n    var i := new Intent(aContext, typeOf(BatteryWidgetProvider));\r\n\r\n    case aIntent.Action of\r\n      Intent.ACTION_SCREEN_ON  : i.Action := SCREEN_ON;\r\n      Intent.ACTION_SCREEN_OFF : i.Action := SCREEN_OFF;\r\n    else\r\n      i := NIL;\r\n    end;\r\n\r\n    if assigned(i) then\r\n      aContext.sendBroadcast(i)\r\n    else\r\n      inherited;\r\n  end;\r\n<\/pre>\n
    First I create the intent I will be sending.  Just to simplify the rest of the method I create this before determining whether it will be needed.  A bit wasteful perhaps but not a major concern I don’t think.<\/p>\n
    I then use a case<\/strong> statement to set the appropriate custom intent constant (string) as the Action<\/strong> of the intent.  I simply NIL<\/strong> the intent reference ‘i<\/code>‘ if the intent I received turns out not to be one of the screen state intents.<\/p>\n
    This is a little demonstration of the fact that Oxygene<\/strong> case statements are more flexible than we are used to in Delphi: they support strings!  This really isn’t your grand-daddy’s Pascal.  \ud83d\ude09<\/p>\n
    If I end up with an intent, I broadcast it.  Otherwise I pass the buck, up to the inherited onReceive<\/code> implementation, just in case.<\/p>\n
    Now is as good time as any to add my actions to the intent-filter<\/code> for the widget provider in the manifest:<\/p>\n
    \r\n      <intent-filter>\r\n        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" \/>\r\n        <action android:name="android.appwidget.action.APPWIDGET_ENABLED" \/>\r\n        <action android:name="android.appwidget.action.APPWIDGET_DISABLED" \/>\r\n        <action android:name="nz.co.deltics.SCREEN_OFF" \/>\r\n        <action android:name="nz.co.deltics.SCREEN_ON" \/>\r\n      <\/intent-filter>\r\n<\/pre>\n
    And finally implement an override of the onReceive method in the widget provider itself to respond to these actions:<\/p>\n
    \r\n  method BatteryWidgetProvider.onReceive(aContext: Context; \r\n                                         aIntent: Intent);\r\n  begin\r\n    case aIntent.Action of\r\n      ScreenStateReceiver.SCREEN_ON  : onEnabled(aContext);\r\n      ScreenStateReceiver.SCREEN_OFF : onDisabled(aContext);\r\n    else\r\n      inherited;\r\n    end\r\n  end;\r\n<\/pre>\n
    The code I needed was ready and waiting on the widget provider class in the form of the onEnable()<\/code>\/onDisable()<\/code> methods, so when I receive a SCREEN_ON<\/strong>\/SCREEN_OFF<\/strong> intent, I simply call the appropriate one of those methods.<\/p>\n
    It is very important that I call the inherited implementation of onReceive()<\/code> in this case since I know for a fact<\/em> that the superclass responds to a variety of other intents necessary to the functioning of an AppWidgetProvider<\/strong> (you may recall this is a specialisation of BroadcastReceiver<\/strong>).<\/p>\n
    Indeed the onEnable()<\/code> and onDisable()<\/code> methods are introduced by this base class and will be called by the inherited onReceive()<\/code> implementation in response to other system generated intents.<\/p>\n
    Just one last thing and it’s all done.<\/p>\n
    Getting the Service Started<\/h3>\n
    To support these screen state intents I have introduced a new service, but the intents that service is designed to support are not intents that we can declare in the manifest, so as things stand currently, this new service will never get started and will never register the receiver that my widget relies on for the screen state notifications.<\/p>\n
    Somewhere I need to start this service myself.<\/p>\n
    I decided that the onEnabled()<\/code> handler of my BatteryWidgetProvider<\/strong> would suit.<\/p>\n
    Starting the ScreenStateService<\/strong> here means that the service is certain to be started at some suitable point when I have an active instance of my widget.<\/p>\n
    Further more, the onEnabled()<\/code> method is also called whenever the device screen comes on (thanks to my handling of that intent).  I am not entirely certain that it is necessary, but it surely can’t hurt that re-starting the service at this point will add further weight to the START_STICKY<\/strong> nature of the service, making it even less likely that the service will be cleaned up unless absolutely necessary.  I think.  Either way I don’t think it can hurt.<\/p>\n
    So I add the following line to my BatteryWidgetProvider.onEnabled()<\/code> method:<\/p>\n
    \r\n    aContext.startService(new Intent(aContext, typeOf(ScreenStateService)));\r\n<\/pre>\n
    All Over Bar the Shouting<\/h3>\n
    My widget now will suspend updates as soon as the screen is turned off – for whatever reason – even before the device has entered sleep, and will resume updates when the screen is turned on.  Since this will start a new alarm schedule, this means the widget will also perform an initial update so that I get an accurate battery level reading instantly.<\/p>\n
    This latter point is worth highlighting.<\/p>\n
    I am running a custom ROM on my Android phone, and this incorporates a battery level reading on the default lock screen.  Interestingly, this is not<\/strong> refreshed when the screen comes on.  As a result, the battery level initially presented on my lock screen is often a little, um, optimistic<\/em>.<\/p>\n
    Also worth mentioning is that I have been running my revised widget on my phone all day for the past 2 days and as far as I can tell, battery use has been no greater than usual but continues to update consistently, so it would appear that the time spent ensuring that my widget behaves itself has been well spent!<\/p>\n
    The final leg in this journey is to get my widget up in the Google Play store.<\/p>\n
    Not that I think it really has anything compelling to offer alongside the myriad other battery widgets that are already there, but it will be a useful exercise in going through the process of getting something approved for the store.<\/p>\n
    An experience which – all being well – I will then also share.<\/p>\n
    \ud83d\ude42<\/p>\n","protected":false},"excerpt":{"rendered":"
    [Estimated Reading Time: <\/span>  7<\/span> minutes]<\/span><\/span>In my previous post I explained how I believed I had solved a problem with my widget, only to discover that it created a different problem in the process. I had believed that IntentService based services were long-lived, but in fact this is not the case. However, the change remains valid for solving the problem […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_feature_clip_id":0,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2},"jetpack_post_was_ever_published":false},"categories":[212,205,4,180],"tags":[153,235,181,234],"class_list":["post-1873","post","type-post","status-publish","format-standard","hentry","category-android-2","category-cooper","category-delphi","category-oxygene","tag-android","tag-custom-intents","tag-oxygene-2","tag-screen"],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_shortlink":"https:\/\/wp.me\/p1TKYv-ud","jetpack_sharing_enabled":true,"jetpack-related-posts":[],"_links":{"self":[{"href":"https:\/\/www.deltics.co.nz\/blog\/wp-json\/wp\/v2\/posts\/1873","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.deltics.co.nz\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.deltics.co.nz\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.deltics.co.nz\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.deltics.co.nz\/blog\/wp-json\/wp\/v2\/comments?post=1873"}],"version-history":[{"count":9,"href":"https:\/\/www.deltics.co.nz\/blog\/wp-json\/wp\/v2\/posts\/1873\/revisions"}],"predecessor-version":[{"id":1899,"href":"https:\/\/www.deltics.co.nz\/blog\/wp-json\/wp\/v2\/posts\/1873\/revisions\/1899"}],"wp:attachment":[{"href":"https:\/\/www.deltics.co.nz\/blog\/wp-json\/wp\/v2\/media?parent=1873"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.deltics.co.nz\/blog\/wp-json\/wp\/v2\/categories?post=1873"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.deltics.co.nz\/blog\/wp-json\/wp\/v2\/tags?post=1873"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}