Android Tutorial Android home screen widgets tutorial - part I

Discussion in 'Tutorials & Examples' started by Erel, Jul 11, 2011.

  1. Erel

    Erel Administrator Staff Member Licensed User

    Basic4android v1.6 adds support for home screen widgets. 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:
    Code:
    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:
    Code:
    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).
    For example if you want to show the main Activity when the user presses on Button1 you can use this code:
    Code:
    Sub Button1_Click
    StartActivity(Main)
    End Sub
    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:
    Code:
    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.
    [​IMG]

    Second part of this tutorial: http://www.basic4ppc.com/forum/basi...oid-home-screen-widgets-tutorial-part-ii.html

    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).
     

    Attached Files:

    Last edited: Jul 7, 2019
    Watchkido1 likes this.
  2. dealsmonkey

    dealsmonkey Active Member Licensed User

    Very nice and just in time for my next app !!

    i assume v 1.6 will be available soon ?

    Neil
     
  3. Erel

    Erel Administrator Staff Member Licensed User

    Beta version will be released today to a group of beta testers. The stable version should be released in about one week.
     
  4. corwin42

    corwin42 Expert Licensed 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?
     
  5. Erel

    Erel Administrator Staff Member Licensed User

    The size of the base Panel determines the widget minimum width and minimum height properties.
     
  6. NeoTechni

    NeoTechni Well-Known Member Licensed User

    Awesome!

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

    Inman Well-Known Member Licensed 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.
     
  8. Erel

    Erel Administrator Staff Member Licensed User

    This is a tutorial about home screen widgets. Questions regarding other features should be asked in the Questions or Wishlist sub forums.
     
  9. Erel

    Erel Administrator Staff Member Licensed User

    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.
     
  10. Inman

    Inman Well-Known Member Licensed 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?
     
  11. enrique1

    enrique1 Member Licensed User

    Thank you Erel!! :icon_clap:

    I was waiting for it!
     
  12. Erel

    Erel Administrator Staff Member Licensed User

    Scrollable widgets are supported by Android 3.0 or above. For now Basic4android doesn't support such widgets.
     
  13. adex1

    adex1 Member Licensed User

    I hope v1.6 will not have so much effect on the beginners tutorials.
     
  14. Cableguy

    Cableguy Expert Licensed User

    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
     
  15. anaylor01

    anaylor01 Well-Known Member Licensed User

    Can you use this to create a launcher? And if so what would be the syntax for that?
     
  16. susu

    susu Well-Known Member Licensed User

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

    corwin42 Expert Licensed User

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

    Sent from my LG-P500 using Tapatalk
     
  18. crt

    crt Member Licensed User

    Awesome, been waiting for this. Time to rewrite a bunch of code. Thanks for all of your hard work.
     
  19. anaylor01

    anaylor01 Well-Known Member Licensed 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.
     
  20. corwin42

    corwin42 Expert Licensed User

    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.
     
Loading...
  1. This site uses cookies to help personalise content, tailor your experience and to keep you logged in if you register.
    By continuing to use this site, you are consenting to our use of cookies.
    Dismiss Notice