Android Tutorial Android home screen widgets tutorial - part I

Status
Not open for further replies.
Edit: widgets are handled with receivers now. See the attached example.

This tutorial will explain how to implement your own home screen widgets (also named App Widgets).

It is important to understand that the widgets are created and managed in another process, different than the process that your application is running in. The home screen application is hosting your widgets.
This means that it is not possible to directly access the widgets views. Instead we are using a special object named RemoteViews which gives us indirect access to the widget views.

Widgets do not support all views types. The following views are supported:
- Button (default drawable)
- Label (ColorDrawable or GradientDrawable)
- Panel (ColorDrawable or GradientDrawable)
- ImageView
- ProgressBar (both modes)

All views support the Click event and no other event.

The widget layout and configuration must be defined with XML files. During compilation Basic4android reads the layout file created with the designer and generates the required XML files.

Each widget is tied to a Service module. Through this module the widget is created and updated.

Creating a widget - step by step guide

- Add a Service module. Note that the service module handling the widget is a standard service.
- Design the widget layout with the designer. First add a Panel and then add the other views to this Panel.
The widget layout will be made from this panel.
- Add code similar to the following code the service module:
B4X:
Sub Process_Globals
    Dim rv As RemoteViews
End Sub

Sub Service_Create
    rv = ConfigureHomeWidget("LayoutFile", "rv", 0, "Widget Name")
End Sub

Sub Service_Start (StartingIntent As Intent)
     RV.HandleWidgetEvents(StartingIntent)
    Sleep(0)
    Service.StopAutomaticForeground
End Sub

Sub rv_RequestUpdate
    rv.UpdateWidget
End Sub

Sub rv_Disabled
    StopService("")
End Sub

Sub Service_Destroy

End Sub
- Compile and run your application. Go to the home screen, long press on the screen and you will see your widget listed on the widgets list.

ConfigureHomeWidget is a special keyword. At runtime it creates the RemoteViews object from the layout and set the events. At compile time the compiler generates the required files based on the arguments of this keyword.
The four parameters are: layout file, event name, update interval and the widget name.
Event name sets the subs that will handle the RequestUpdate and Disabled events.
The widget can be configured to update itself automatically. The interval, measured in minutes, defines how often will the widget request to update itself. Set to 0 to disable automatic updates. Updating the widget too often will have a bad impact on the battery. The minimum value is 30 minutes.
Widget name - the name that will appear in the widgets list.

As these arguments are read by the compiler, only strings or numbers are accepted.

Events:
B4X:
Sub Service_Start (StartingIntent As Intent)
    If rv.HandleWidgetEvents(StartingIntent) Then Return
End Sub
The above code checks the Intent message that caused this service to start and is responsible for raising the events related to the widget. It returns true if an event was raised.
The widget raises two events. RequestUpdate is raised when the widget needs to update itself. It will fire after adding the widget to the screen, after the device has booted, based on the scheduled updating interval (if set) or after the application was updated.
The Disabled event is raised when the last instance of our widget is removed from the screen.

As mentioned above all views support the Click event. All that needs to be done in order to handle the click event of a button named Button1 is to add a sub named Button1_Click (the sub name should actually match the EventName property which is by default the same as the name).

[/code]Modifying the widget:
It is not possible to directly access the widget views. Instead we need to use one of the RemoteView.Set methods.
If we want to change the text of a label named Label1 then we need to write the following code:
B4X:
rv.SetText("Label1", "This is the new text.")
'do more changes if needed
rv.UpdateWidget
After writing all the changes we call rv.UpdateWidget to send the updates to the widget.

A simple example is attached.
The example adds a simple widget. The widget doesn't do anything useful.
SS-2011.07.11-12.55.04.png

Note that it is recommended to test widgets in Release mode (the widget will fail in debug mode when the process is started by the OS).
 

Attachments

  • HomeWidgets.zip
    24.6 KB · Views: 813
Last edited:

Jim Brown

Active Member
Licensed User
Longtime User
Great work Erel. I have updated my WordLearn App with widget support. It works a treat:

firstwidget.png
 

enrique1

Member
Licensed User
Longtime User
Quick question,

when the widget is updated, run again Service_Start or Service_Create methods??


EDIT: Ok solved, Sub wid_RequestUpdate ^^'
 
Last edited:

anaylor01

Well-Known Member
Licensed User
Longtime User
Sorry. I am using the wrong terms. I mean I want to write a widget I can put icons on that will open other applications. I have been able to do it with apps I have written by manually putting the icons in the designer. I know I can use pm.GetApplicationIcon("com.google.android.youtube") in an app but I don't think I can do this with B4A widget.
 

corwin42

Expert
Licensed User
Longtime User
Sorry. I am using the wrong terms. I mean I want to write a widget I can put icons on that will open other applications. I have been able to do it with apps I have written by manually putting the icons in the designer. I know I can use pm.GetApplicationIcon("com.google.android.youtube") in an app but I don't think I can do this with B4A widget.

This should be possible. Use GetApplicationIcon() to get the drawable and set its bitmap with RemoteViews.SetImage() to an ImageView on the Widget.
 

Cableguy

Expert
Licensed User
Longtime User
Actually I think not. If I have understood correctly the entire widget has only one click event... for the whole widget!
 

corwin42

Expert
Licensed User
Longtime User
Actually I think not. If I have understood correctly the entire widget has only one click event... for the whole widget!

No. The only event supported is the click event but every view on the widget can have its own.
 

anaylor01

Well-Known Member
Licensed User
Longtime User
Each imageview has its own click event. Can you give me the syntax that you were talking about earlier
 

anaylor01

Well-Known Member
Licensed User
Longtime User
Another question about the widget size. I have the panel set for a height of 100 but it seems that it is taking up double that size. Any ideas?
 

corwin42

Expert
Licensed User
Longtime User
Another question about the widget size. I have the panel set for a height of 100 but it seems that it is taking up double that size. Any ideas?

I discussed this with Erel in another thread. B4A sets the Widget minWidth and minHeight values the same as your base panel. The problem here is that the cell size in portrait and landscape is different and you have to set the minimum of both variants for minWidth and minHeight. B4A currently does not support this very good.

You should calculate the values for minWidth and minHeight yourself with the formula (cellcount * 74) - 2 and then put these values manually in Objects/res/xml/<widget>_info.xml. Then make this file read only and be happy.
 

MuuSer

Member
Licensed User
Longtime User
You should calculate the values for minWidth and minHeight yourself with the formula (cellcount * 74) - 2 and then put these values manually in Objects/res/xml/<widget>_info.xml. Then make this file read only and be happy.
Thanks, Markus. Your advice is very helpful. First time it seems that no changes in behavior of the widget, but after removing widget from home screen and putting it back - size is just as it must be. Thanks again.
 

corwin42

Expert
Licensed User
Longtime User
It is better to just set the panel size to this value instead.

The problem is that you then loose much space. If you want to be compatible with all device resolutions I must agree. On a device with 240x320 it is really a problem if you size your widget bigger but on devices with high resolution you get very small widgets with large free borders. I'm just playing around with different widget sizes in portrait and landscape mode. There is really no perfect solution for widget sizing.
 

corwin42

Expert
Licensed User
Longtime User
Maybe I'm missing something. There should be no difference between setting the panel size to the calculated value or setting it manually in the XML file.

Attached is a screenshot of my current homescreen. The lower weather widget was created with B4A. The base panel has a size of 310x90 and I think it has the correct size for my homescreen (though it is not centered correctly now).

If I size the widget 294x72 (which is the maximum "official" size) it looks really small and has big borders.

If your widget is 4x4 the height is much worse. Then I could size my widget 310x390 without problems. The "official" size would be 294x294 with is nearly 100 dp smaller.
 

Attachments

  • AHWeather_Screenshot.jpg
    AHWeather_Screenshot.jpg
    55.3 KB · Views: 990
Last edited:

dealsmonkey

Active Member
Licensed User
Longtime User
Here is a screen grab of one of my widgets on an HTC Desire.

What I did was lay down a transparent panel of 314 x 78, then put a visible panel on top which is 300 x 78 with all the controls on that visible panel. I then adjusted the second panel to center it

Neil
 

Attachments

  • device.jpg
    device.jpg
    14 KB · Views: 890
Status
Not open for further replies.
Top