Widget UI

Ok, so we've seen how we need to add to our apps AndroidManifest.xml and create an AppWidgetProvider descendant to code our Widget, but how do we control its appearance? If you look again at the <receiver> entry in AndroidManifest.xml, you'll see a reference to @xml/twitter_widget. Here's how that looks:

<?xml version="1.0" encoding="utf-8"?>
<appwidget-provider 
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="292dp"
    android:minHeight="72dp"
    android:updatePeriodMillis="86400000"
    android:initialLayout="@layout/widget"
    android:configure="com.androidacademy.tutorials.twitterwidget.TwitterWidgetActivity"
    >
</appwidget-provider>

This is more framework plumbing which Android expects Widgets to provide. Notice how it defines your Widgets width and height in device-independant pixels - there's a lot more info on this on Androids Widget Design Guidelines page. A place to define the update frequency is present, which although we don't need it here is important for the clocks/newsfeeds etc. The entry we're interested in now is the @layout/widget one - that's how the Views for the Widget are wired in. There's also an (optional) entry for configuration, which we'll cover soon. Here's the Widget layout as defined by @layout/widget:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" 
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    >
    
    <ImageView
        android:id="@+id/widgetFrame"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content" 
        android:scaleType="fitCenter"
        android:src="/@drawable/widgetframe"
        />
        
     <TextView 
         android:id="@+id/twitterText"
         android:layout_height="48dp"
         android:layout_width="wrap_content"
         android:layout_marginTop="26dip"
         android:layout_marginLeft="66dip"
         android:layout_marginRight="22dip"
         android:gravity="center_vertical"
         android:lines="3"
         style="@style/TwitterText"    
         />
    
</RelativeLayout>

If that strikes you as looking just like a layout for a View you'd use in a regular Android app, that's because it is! You can get as fancy as you like here, within reason. Now you can see how all those complex looking weather Widgets seem to have irregular shapes - it's just because they use images with transparent backgrounds whilst still fitting into the dimensions defined in their Widget xml definition. The other parameter in the Widget definition xml was for android:configure, and we had an entry to one of our Activities called TwitterWidgetActivity. This is a regular Activity - it's a child of Activity and has the same lifecycle methods common to all Activities. The only thing special here is the fact that it's been wired in to launch when the Widget is added to the home screen. This is intended to let your users configure your widget, and it's often the case that it makes sense to do that right at the point when the user's just added it to their home screen. Since this isn't always the case, this entry is optional. In our Widget, we do want it - it means as soon as the Widget is added, a dialog with the text area letting the user send a tweet appears right away.

Our UI consists simply of a background image and a TextView placed appropriately over it - that's what our app will populate when tweets are sent.