Text Clock – Part 2

In the previous article we got the project set up for our Text Clock app, and added the business logic code. In this article we’ll begin creating an App Widget that the user can add to their home page.

The first thing that we need to do to create an App Widget is to create an instance of AppWidgetProvider. For now we’ll keep this fairly simple:

public class TextClockAppWidget extends AppWidgetProvider
{
    private Context context = null;

    @Override
    public void onUpdate( Context context, 
        AppWidgetManager appWidgetManager, 
        int[] appWidgetIds )
    {
        this.context = context;
    }
}

This call will be called by the OS to manage our widget. At the moment we’re just storing a reference to a Context which we’ll require later on. AppWidgetProvider extends BroadcastReceiver so we need to declare it as such in the Manifest. However, because AppWidgetProvider is a specialised form of BroadcastReceiver, we need to provide some additional metadata which is specific to AppWidgetProvider in an XML file:

The appwidget_info file is as follows:

This file will be expanded in to an AppWidgetProviderInfo instance at runtime, but let’s look at the individual attributes:

• minWidth and maxWidth – These are the default dimension of the widget. For this app we’re going to create a widget which is two home screen cells wide by one cell high. A full explanation of these values can be found here.
• updatePeriodMillis – this is how often the OS will make a call to our AppWidgetProvider to update the widget. On the face of it, this should suit our needs to update the time of the widget. In reality, however, the maximum update rate using this mechanism is every thirty minutes, and a clock which only updates every thirty minutes is pretty useless. Therefore we’ll need to look at an alternate mechanism for updating the widget and we use a default value here.
• initialLayout – this is a default layout which will be used for the widget, and displayed automatically when the widget is added to the users’ home screen. We’ll look at the layout shortly.
• previewImage – on API 11 (Honeycomb 3.0) devices and later, a preview image can be added which will be shown in the widget picker. We’ll include a screen capture here. This will be ignored on pre-API 12 devices.
• resizeMode – beginning with API 12 (Honeycomb 3.1) it was possible to resize widgets. A fixed size widget is perfect for our needs, so we’ll stick with that. One again, this attribute will be ignored on pre-API 12 devices.

As we can probably guess from the initialLayout attribute we need to create a layout in res/layout/appwidget.xml:

Here we have defined a LinearLayout with a background (which we’ll define in a moment) which contains three TextView widgets to display the our text. We have set styles for each of these which we’ll look at shortly. What may be slightly confusing is why it is all wrapped inside a FrameLayout – isn’t it inefficient to wrap our LinearLayout inside a FrameLayout in this way? The reason that we need to do this is that the margin behaviour of app widgets changed in API 14 (Ice Cream Sandwich) where app widgets automatically get a margin added. In order to maintain uniformity across older and newer devices we need to compensate for this by applying a margin value for pre-API 14 devices. We do this by adding res/values/dimens.xml which contains the definition of @dimen/widget_margin:

    8dp
    22dp

This is fine for older devices where we need to manually apply the margin, but for API-14 and later devices the OS will apply the margin so we need to override this for newer devices by creating res/values-v14/dimens.xml which will be selected automatically by the OS is API 14+ devices:

    0dp

The background for the LinearLayout is defined in res/drawable/widget_background.xml:

This defines a semi-transparent rectangle with rounded corners, and a thin “holo’ blue outline.

Finally we define the text styles in res/values/styles.xml:

Finally we need to define the colours used. While these colours are available baked in to the OS on devices which support holo, we’re going for backwards compatibility, so we’ll include them in res/values/colors.xml:

    #ff00ddff
    #ff33b5e5

We’ve crammed quite a lot here but much of it has been covered in much more depth in the past so we’ve skimmed through things a little.

If we now have a look at where we are. If we install this and go to the widget selection page on our device we can see our widget listed, along with the preview image:

If we copy this on to our home page the widget background is displayed, but we currently aren’t actually displaying anything in the TextViews because we haven’t set the text yet:

In the next part of this series we’ll set this text to the current time.

The source code for this article can be found here, and TextClock is available from Google Play.

© 2013 – 2014, Mark Allison. All rights reserved.

Copyright © 2013 Styling Android. All Rights Reserved.
Information about how to reuse or republish this work may be available at http://blog.stylingandroid.com/license-information.