Free Android app covering all aspects of addiction, including prevention and treatment

App Widgets tutorial: part 2

  • Written by  Clive

Here's how you can create an app widget...part 2

Android's App Widget tutorial part 2 icon

App Widgets are mini apps that give users immediate access to important functions of an app.

We mostly use App Widgets to display important information about an app on a device’s Homescreen.

You can create your own app widgets. Here's part 2 of our tutorial where we show you how to create and use App Widgets in your apps.

Have you read the first part of the tutorial, App Widget tutorial: part1?

onDisabled()

Called in response to the ACTION_APPWIDGET_DISABLED broadcast which is sent when the last instance of the widget is deleted.

We disable our BroadcastReceiver, MyWidgetBroadcastReceiver here.

Android's App Widget tutorial onDisabled()

onDisabled() is called when the last instance of our widget is deleted. We use it to disable our BroadcastReceiver

Note the following:

  • pm – the package manager. Allows us to get information about application packages installed on the device
  • setComponentEnabledSetting – this is where we set the state of the broadcast receiver. There are three parameters:
    • the component name – our broadcast receiver
    • the state of the component – we set it to disabled (it’s no longer needed)
    • flags – optional behaviour. We don’t want to kill the app containing the widget
onDeleted()

onDeleted() is called each time our widget is deleted.

We simply loop through the array of ID’s of the widgets that need deleting and delete their labels from the preference file.

updateOurWidget()

Our custom method where we do the actual updating of the widget.

Android's App Widget tutorial updateOurWidget()

Our custom method where we update our widget

Note the following:

  • we pass in 4 parameters:
    • the context
    • the app widget manager
    • the widget’s ID
    • the widget’s label
  • currentTime – we get the current time which we display in the widget
  • pendingIntent – we create a pending intent which will start the MyActivity activity when the widget’s button is clicked
  • views – our RemoteViews object containing the widget
  • we set the two text views, time and label, to display the current time and the latest label
  • setOnClickPendingIntent – handles the button click and launches the pending intent to start the MyActivity activity
  • updateAppWidget – we update the widget. We pass two parameters:
    • the widget’s ID
    • the RemoteViews object, views – our widget

Our Broadcast Receiver: MyWidgetBroadcastReceiver

The Android System broadcasts an appropriate message each time the user changes the time zone or sets the time on the device. Our BroadcastReceiver is tuned in to receive these messages so that we can update the widget’s time display.

Android's App Widget tutorial onReceive()

We use our BroadcastReceiver’s onReceive() method to update our widget to reflect the new time

Note the following:

  • we get the action out of the broadcast intent that our broadcast receiver received – the system broadcasts the intent when the user changes the time zone or sets the time
  • we use an if statement to check whether the broadcast intent’s action matches:
    • ACTION_TIMEZONE_CHANGED – the device’s time zone setting has been changed
    • ACTION_TIME_CHANGED – the device’s time setting has changed
  • If the action matches either of these then we go ahead and update the widget to reflect the changed time

You need to register the BroadcastReceiver in the AndroidManifest.xml file. Here’s how we declare MyWidgetBroadcastReceiver in the manifest file:

Android's App Widget tutorial manifets Broadcastreceiver

We register our BroadcastReceiver in the manifest file

Note the following:

  • Our broadcaster receiver will only receive broadcast intents containing the actions that we have included in the intent filter. The system broadcasts intent messages when the time zone has changed or the time has been set. Our broadcast receiver will receive these broadcasts

Configuring the widget

You can include an activity which enables the user to configure the widget when they add it to the Homescreen. This configuration activity is automatically launched by the App Widget host.

Declare the activity in the manifest as you would any other activity.

Android's App Widget tutorial configuration activity manifest

We declare the configuration activity in the manifest

Note the following:

  • The host starts this activity by including the ACTION_APPWIDGET_CONFIGURE action in its intent request. We must therefore include the action in our activity’s intent filter for our activity to be able to accept this intent. See Intents and Intent Filters

You also have to declare the activity in the AppWidgetProviderInfo XML file:

Android's App Widget tutorial AppWidgetProviderInfo

We declare our configuration activity using the configure attribute in the AppWidgetProviderInfo XML file

MyWidgetConfigureActivity activity

Our configuration activity is started when the widget is first added to the Homescreen, the host. It allows the user to configure the widget to suit their needs.

In our widget, the user enters a label and presses a button to save it. The label is displayed in the widget.

Android's App Widget tutorial configuration activity screenshotConfigure

Our configuration activity lets the user enter a label for the widget

This is what happens in the configuration activity:

  • In onCreate(), we set the returned result to RESULT_CANCELLED. This ensures that the widget is not added to the Homescreen if the user presses the Back button. You’ll have a better understanding of this if you see this activity as being started for a result. Check out the tutorial, Start an Activity for a result for more on this
  • We set the layout to be used and get instances of the text field and the button
  • We include a listener which handles the button press. The user can enter some text to be displayed as a label in the widget. They then press the button, where:

The other methods in our configuration activity

setWidgetLabelPreference()

Here we save the label entered by the user in the shared preferences file. We use widgetLabel_ plus the widget’s ID as the key and the text input as the value.

loadWidgetLabelPreference()

Called in onUpdate() in MyWidgetProvider. This method gets and returns the label identified by the widget’s ID from the preference file.

deleteWidgetLabelPreferences()

Called in onDeleted() in MyWidgetProvider. This method deletes all the widget labels identified by the widget’s ID from the preference file.

MyActivity activity

This activity is started when the user presses the button in the widget.

Android's App Widget tutorial configuration activity screenshotMyActivity

Pressing the button in the widget starts the MyActivity activity and displays an image

I hope that you have found this tutorial helpful.

This project was created using Android Studio.

You can download the project files here Download icon

Are you using Eclipse or another IDE? Here's how you can use this project's Android Studio files.