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

Wembly

Member
Licensed User
Longtime User
You are correct. Make sure to run your app in Release mode. If it still crashes then you need to check the logs (connect with USB debug mode).

Erel - The app is running in release mode in addition I've now managed to capture the error generated when the app crashes:

java.lang.RuntimeException: Unable to create service uk.co.androidapps4u.ShiftCalendar.widget7day: java.lang.RuntimeException: java.lang.reflect.InvocationTargetException
at android.app.ActivityThread.handleCreateService(ActivityThread.java:2373)
at android.app.ActivityThread.access$1600(ActivityThread.java:130)
at android.app.ActivityThread$H.handleMessage(ActivityThread.java:1277)
at android.os.Handler.dispatchMessage(Handler.java:99)
at android.os.Looper.loop(Looper.java:137)
at android.app.ActivityThread.main(ActivityThread.java:4745)
at java.lang.reflect.Method.invokeNative(Native Method)
at java.lang.reflect.Method.invoke(Method.java:511)
at com.android.internal.os.ZygoteInit$MethodAndArgsCaller.run(ZygoteInit.java:786)
at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:553)
at dalvik.system.NativeStart.main(Native Method)
Caused by: java.lang.RuntimeException: java.lang.reflect.InvocationTargetException
at uk.co.androidapps4u.ShiftCalendar.widget7day.onCreate(widget7day.java:33)
at android.app.ActivityThread.handleCreateService(ActivityThread.java:2363)
... 10 more
Caused by: java.lang.reflect.InvocationTargetException
at java.lang.reflect.Method.invokeNative(Native Method)
at java.lang.reflect.Method.invoke(Method.java:511)
at uk.co.androidapps4u.ShiftCalendar.widget7day.onCreate(widget7day.java:31)
... 11 more
Caused by: java.lang.RuntimeException: java.lang.NullPointerException
at uk.co.androidapps4u.ShiftCalendar.main.initializeProcessGlobals(main.java:921)
... 14 more
Caused by: java.lang.NullPointerException
at anywheresoftware.b4a.BA.<init>(BA.java:106)
at uk.co.androidapps4u.ShiftCalendar.translation.innerInitialize(translation.java:12)
at uk.co.androidapps4u.ShiftCalendar.translation._initialize(translation.java:60)
at uk.co.androidapps4u.ShiftCalendar.main._process_globals(main.java:1732)
at uk.co.androidapps4u.ShiftCalendar.main.initializeProcessGlobals(main.java:905)
... 14 more

The code for the service is:

B4X:
Sub Process_Globals

    'These global variables will be declared once when the application starts.
    'These variables can be accessed from all modules.

    Dim widget As RemoteViews
  
End Sub

Sub Service_Create
  
    widget = ConfigureHomeWidget("Widget7Day","widget",60,"Shift Calendar 7 Days")
    widget.UpdateWidget
  
 
End Sub

Sub Service_Start (StartingIntent As Intent)

    If widget.HandleWidgetEvents(StartingIntent) Then Return

End Sub

Sub Service_Destroy

End Sub

Sub widget_RequestUpdate
    ...

As mentioned previous the widget works fine as long as the app is running memory, but when they click the widget when the app is not running in memory then it crashes.

Any ideas I've searched but not found anything useful information.

Thanks!
 
Last edited:

Wembly

Member
Licensed User
Longtime User
Thanks Erel but just found the issue - I had an incorrect initialize in Process Globals which I've now moved and all is good.
 

CyclopDroid

Well-Known Member
Licensed User
Longtime User
It's possible start the Widget after the install Application? Or start it, when the Widget it's moving of Widget Menu to screen phone?
Thanks.
 

CyclopDroid

Well-Known Member
Licensed User
Longtime User
My widget can't automatic start after reboot, how to fix this?
Have you insert the True boolean to StatAtBoot into Service Attribute of you widget code?

B4X:
#Region  Service Attributes
    #StartAtBoot: True
#End Region

Happy New Year to all ;)
 

Cebuvi

Active Member
Licensed User
Longtime User
Hello Erel,

I have written a small widget and I can not fire the click events. Some day ago I write another widget and it worked perfectly and still does, but not this example.

I send you the code.

Thanks

Cesar
 

Attachments

  • W2.zip
    9 KB · Views: 413

Cebuvi

Active Member
Licensed User
Longtime User
Hello Erel,

I have written a small widget and I can not fire the click events. Some day ago I write another widget and it worked perfectly and still does, but not this example.

I send you the code.

Thanks

Cesar

Hi,

I solved the problem, I had two layers with the same name. It seems that every project must have different names for the elements: layouts, service mudule, etc

Thanks

Cesar
 

demasi

Active Member
Licensed User
Longtime User
Hello, I'm trying to make a widget in B$A 4.30, I tried Erel's example, but in my Sony Xperia Z3 with Android 5.02 the widget does not appear in the launcher, so I cant install it to screen. I tried in another phone, samsung note4 with android 5 and it worked as a charm.
all widgets I've installed in my Sony from Google Play worked with no problems.
can someone give some tip to solve this?
 

imgsimonebiliato

Well-Known Member
Licensed User
Longtime User
Hello,
I think that the service doesn't start... I don't see it in the log.
Is it possibile? How can I check this?
 

lemonisdead

Well-Known Member
Licensed User
Longtime User
Hello,
When you put the widget on the Launcher's screen, it should start. You should see that in the logs.
If you want to check that directly in the system, you should see in the Android settings \ Apps \ Currently running your app's icon and the name of the service
 

imgsimonebiliato

Well-Known Member
Licensed User
Longtime User
But the widget isn't created on the widgets list
 

lemonisdead

Well-Known Member
Licensed User
Longtime User
So please could you check in \Objects\res\xml that a XML file exists for the widget ? Its name should be : [your widget's service name]_info.xml
 

imgsimonebiliato

Well-Known Member
Licensed User
Longtime User
So please could you check in \Objects\res\xml that a XML file exists for the widget ? Its name should be : [your widget's service name]_info.xml

Yes.. It has got the same name of the service + _info.xml
 

lemonisdead

Well-Known Member
Licensed User
Longtime User
And of course, in Service_Create you have used the ConfigureHomeWidget(layout, event, refreshtime, widget's name,false). If yes, sorry, I won't be able to help more. Only Erel and experts could
 
Status
Not open for further replies.
Top