fbpx
Android widgets - Basics

Android widgets – basics

Reading Time: 7 minutes

If you check the most successfull apps on Google Play, then you can realize thet they are the simplest ones as well. In many cases the users need to have a simple user interface where they can get the needed informations as fast as possible. Here comes Android Widgets to the rescue. In this basics tutorial you are going to learn how you can implement very simple Android widgets, which can only open the activity by clicking on a button.

What are Android Widgets?

App Widgets are realy small, miniature applications which are embedded in the other applications (like the Home screen) and they can receive periodic updates.

Widgets are available since Android 1.6 (Donut). So, they are available almos since the existance of the Android system.

App Widgets are addons, and they gonna be available after the user installs the app on a device. An app can have as many widgets as the users want, but a widget can’t be a stand-alone app without an associated app.

You can add widgets to the home screen, if you touch and hold any blank space on the home screen. Then you can choose the Widgets options. From the list just click on the widget or you can drop on the blank space as well.


Android Widgets
Source: Android Codelabs

From Android 5.0 you can add widgets only to the Home screen. The previous Android versions allow you to place widgets on the lock screen as well.

An app widget can get the data periodically. It can be by the system or by the connected associated app through a broadcast Intent.  An app widget is a broadcast receiver that accepts those Intents.

An Android Widget can perform action on it as well. Like in our example, we gonna start the associated Activity by clicking on the widget. Widgets can have many views, and they have such events one-by-one.

The sample app

As you can see, our sample application going to be very simple. The widget will have a simple one color background with a button. If you click on the button, then it will open up the MainActivity.

Step 1 – Create new project

First thing first, we gonna create a whole new project. For this, launch Android Studio. If you see the “Welcome page”, then click on the “Start a new Android Studio project”. If you have an open project, then from the “File” menu select “New”, then “New Project”. After thet, this window will popup.

Here select the “Empty Activity” option. In the next window, we should provide some information about the newly created app.

This tutorial will contain very few code, but still we have to select the programming language. As the other tutorials on this website, this will be written also in Kotlin. So, select from the dropdown list the Kotlin language.

From the next list of the “Minimum SDK” select API 21. In our case API 21 gonna be enough.

If you are done, click on the “Finish” button. The build can take few minutes. Be patient! 😉

When the build has been finished, then you should see the open MainActivity::class and next to this the activity_main.xml files.

Step 2 – Add the Widget

You can do create the widget manually, or you can add it using Android Studio. In this tutorial we are going to select the second option. In this case Android Studio is going ot prepare for us the needed files.

So, with the right mouse button click on the main source set (where you can find the MainAcitvity.kt file as well). Then, from the quick menu select New, then the Widget option. From the submenu choose the App Widget option.

      1. Name the App Widget as “AppWidget”… very straightforward. 😎
      2. In the Placement option you can select where the user can place the widget.
        We gonna have it only on the Home-screen.
      3. At the left, on the green screen, you can see a grid. The user can resize the widget horizontally and vertically fitting to this grid.
        We gonna give the possibility to resize the widget in all directions.
      4. You can set the minimum width and hight, which are in our case 2 and 2.
      5. When the user places the widget on the screen, then at the first time you can show a configuration screen, where the user can make some settings.
        For now leave it unchecked.
      6. Of course, our project will be written in Kotlin.

Finally, click on the Finish button and Android Studio will generate the needed files.

Android Widget files

After the generation, we should talk about the created files, which are:

      • AppWidget.kt
        This file is the widget provider. A Kotlin file which defines the behavior for our widget. The most important functionality is to handle widget update intents.
      • app_widget.xml
        This file contains the layout of the widget, which is based on RemoteViews elements, rather the normal View hierachy. Albeit we gonna create the layout in the same way. Using Remote views we can display view hiearachy outside of the app.

      • xml folder
        This folder is created in the res folder, and it contains the settings xml file for the widget.
      • app_wiget_info.xml
        This XML configuration file is usually called the provider-info file. It contains properties of our widget, for example the layout file, the width and hight, configuration file, preview image and the frequency of the periodic update as well.

One more thing, what you should know is that Android Studio has added some lines to the AndroidManifest.xml file as well.

Android Studio has added a tag to the xml file, which defines the about widget-update, super class and the info xml file.


AndroidManifest.xml

Step 3 – Widget layout

As we have talked about earlier, we are going to have only 1 Button in the layout of the Widget. This Button is going to open the MainActivity.

So, open up the app_widget.xml file from the res->layout folders, where currently we have a RelativeLayout, which contains a TextView.

I like better to use ConstraintLayout, but unfortunetly for Android Widget we can’t use it. So, we gonna leave the RelativeLayout as the root ViewGroup, but we gonna change the TextView to a Button.

After some modifications the layout should look like below.


app_widget.xml

Step 4 – App widget info - previewImage

In this step we gonna change the preview image of the widget. We can do in the app_widget_info.xml file, which contains the properties of the widget. Then, you can find in the res->xml folders.

First, we gonna add a simple star icon to the app. This star will be shown when the user browses the widgets on the device.

So, click with the right mouse button on the drawable folder, then New, then Vector assets. Next a window will popup. Here click on the Android icon in the row of Clip Art and search for the star in the search box.

Thenafter rename the asset to “ic_star” and change its color to yellow.

Android Studio - Create New Vector Asset

If you are done, then click on the Next and the Finish buttons.

Finally, change the previewImage property in the app_widget_info.xml file to 

android:previewImage=“@drawable/ic_star”

Step 5 – The AppWidget::class

The last step before we can run the widget is to start the MainActivity::class when we click on the Start button. We can do it in the AppWidget::class. So, open it from the main source set.

First of all, we have to check the source code in detailes. The AppWidget::class is extended by AppWidgetProvider::class which identifies this class as a widget provider class.

Because of the inheritance, we can override some methods, which are executed in different events. For example when we add the first instance of the widget, then the onEnabled() method gonna be fired. When we remove the last instance, then the onDisabled() method will be executed.
Note that, the onEnabled() method will be fired when you add the first instance of the widget. If you add some more, then this won’t run.
This is true for the onDisabled() method as well. It will run only when you delete the very last instance of the widget.

Outside of the class is the updateAppWidget() method. This method is called form the onUpdate() method. Here we can udpate the views inside of the widget, add click event to them or even we can change the properties of the widget as well.

After the brief explanation we gonna add some lines to the file.
Ok os, first we gonna remove one 😎, because we don’t want to set the text of the button. So, remove this line from the updateAppWidget() method.

views.setTextViewText(R.id.appwidget_text, widgetText)

Thenafter we gonna set the onClick listener for the button to send the pending intent. Specifically for this action, the RemoteViews::class provides a shortcut method called setOnClickPendingIntent(). So, add the below call to the updateAppWidget() method, before the last line.


setOnClickPendingIntent

Now you should have an error, because we haven’t created the getPendingIntent() method yet, which gonna create a PendingIntent to the MainActivity::class. So, copy and paste the below method at the end of the AppWidget.kt file.


getPendingIntent()

Run the app

Finally, it is time to run the app. 
Note that, when you run the app, the MainAcitivty::class will be started, because this is the launcher activity.

To test the widget, go to the Home screen, find there a blank space, tap on it and hold there your finger. After 1-2 seconds a new menu line gonna be visible. There you gonna find the Widgets option as well. Click on it and find our app in the list, which has a yellow star icon.

Then you can add the widget to the Home screen by clicking it, and the device take it to the next free space on the Home screen. 
You can add a widget also if you hold on it your finger and with the drag-and-drop technik you move it to a free space.

GitHub

The source code is available on GitHub, check it out and download it using the below link.

GitHub

Questions

I hope the description was understandable and clear. But, if you have still questions, then leave me comments below! 😉

Have a nice a day! 🙂

Click to rate this post!
[Total: 1 Average: 5]

Follow and like us:

Leave a comment

stay informed!

Subscribe to receive exclusive content and notifications