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: 814
Last edited:

dealsmonkey

Active Member
Licensed User
Longtime User
Very nice and just in time for my next app !!

i assume v 1.6 will be available soon ?

Neil
 

corwin42

Expert
Licensed User
Longtime User
Looks nice. :sign0098:

Time for new beta. :D

How is it possible to set the widget dimension like 1x1, 2x1, 4x1, 4x2 etc. Is this derived from the layout size?
 

NeoTechni

Well-Known Member
Licensed User
Longtime User
Awesome!

Any ETA on preferences activities? Once you get that you pretty much have everything along these lines
 

Inman

Well-Known Member
Licensed User
Longtime User
Is it compulsory to create layout files with visual designer? I mean can we create the views dynamically at run time, like for example when I check the RSS feed and there are only 2 items, I only need 2 labels, whereas if there are 5 items I need 5 labels.
 

Erel

B4X founder
Staff member
Licensed User
Longtime User
Is it compulsory to create layout files with visual designer? I mean can we create the views dynamically at run time, like for example when I check the RSS feed and there are only 2 items, I only need 2 labels, whereas if there are 5 items I need 5 labels.
Yes. It is not possible to add views at runtime. Widgets do not support it. You can however add extra views and play with their visibility.
 

Inman

Well-Known Member
Licensed User
Longtime User
Thats ok. Visibility should be fine.

One more question. There are a certain kind of widgets available called scrollable widgets. There aren't many. In fact there is only a handful available. Here is one such widget.

https://market.android.com/details?id=org.koxx.pure_news

You also need a different launcher like ADW.Launcher or Launcher Pro for scrollable widgets to work. Since widgets don't support ScrollViews, any idea how these widgets are implemented?
 

Cableguy

Expert
Licensed User
Longtime User
I hope v1.6 will not have so much effect on the beginners tutorials.

Of course not...it's an evolution, not a complete redesign! We'll just have a few more new stuff to write about in the WiKi
 

anaylor01

Well-Known Member
Licensed User
Longtime User
Can you use this to create a launcher? And if so what would be the syntax for that?
 

susu

Well-Known Member
Licensed User
Longtime User
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.

I want to make a clock widget that changes itself every minute, is it possible? :confused:
 

corwin42

Expert
Licensed User
Longtime User
I want to make a clock widget that changes itself every minute, is it possible? :confused:

Yes. Just let your service start himself every minute and do the update of the widget.

Sent from my LG-P500 using Tapatalk
 

crt

Member
Licensed User
Longtime User
Awesome, been waiting for this. Time to rewrite a bunch of code. Thanks for all of your hard work.
 

anaylor01

Well-Known Member
Licensed User
Longtime User
If I understand correctly the layout and the images have to be configured at design. There is no changing the layout or image files are runtime. So creating a functional launcher would not be possible.
 

corwin42

Expert
Licensed User
Longtime User
If I understand correctly the layout and the images have to be configured at design. There is no changing the layout or image files are runtime. So creating a functional launcher would not be possible.

With the support of home screen widgets you are able to create widgets. But this has nothing to do with a launcher. A launcher "runs" the home screen widgets. You can not create a launcher with B4A.

The layout of homescreen widgets has to be created at design time. The images of course can be changed later.
 
Status
Not open for further replies.
Top