B4A Class DOTips 2.7 - show an overlay for app tips

Class Module: DOTips
Author: Dave O'Brien
Code Version: 2.7
Last Mod: 29 Nov 2022

Changes in this version:

- Fixed crash on showing tips for views on certain versions of Android (e.g. Android 11 Go Edition)


DOTips is a free B4A class for showing "spotlight" tips in your app.

These are commonly used for tutorials, onboarding, or showing users what's new. The tips are overlaid on your UI using a semi-transparent background, and can highlight a UI control or an arbitrary area, show a picture, or just show text.

To use, first add this class and its required libraries:
- Add this class module to your B4A project using "Add Existing Modules".
- In the Libraries Manager, make sure these internal (and free) libraries are ticked:
- JavaObject​
- StringUtils​
- Accessibility

Create a variable for the tips:
- In the activity's Sub Globals, add Dim tips As DOTips
- In the activity's Activity_Create, add tips.Initialize(Me, Activity, "tips")

To show tips, add them to the tips list and call Show:

B4X:
tips.addGeneralTip("Insert title here", "Insert description here")
tips.addPictureTip("picture.png", "Insert description here")
tips.addTipForView(someView, "Insert title here", "Insert description here")
tips.addTipForArea(someRect, someScrollview, "Insert title here", "Insert description here")
tips.show
This will show the tips in order, using the default color, text, and automatic positioning (which adjusts to the location of the view).

Note: If a view is not visible when Show is called, that tip is skipped.

To customize tips:
- Set the properties you want first. All tips you add after that will use those settings.
B4X:
tips.HighlightColor = Colors.Magenta
tips.LandscapePosition = tips.POSITION_LEFT
tips.addTipForView(someView, "Insert title here", "Insert description here")

To hide the tips when the device's Back button is tapped, add this:
B4X:
Sub activity_KeyPress(KeyCode As Int) As Boolean
   If (tips.Visible = True) And (tips.CanSkip) Then
      tips.hide(True)
      Return True
   else...

To trigger something after the tips are closed, use the OnHide event:
B4X:
sub tips_OnHide(tipsSkipped As Int)
   'do something here if desired
end sub

To resume tips after orientation changes, use GetIndexOfCurrentTip and Resume.
In the demo code, see the activity_pause and activity_resume subs.

To hide the Skip All button, set canSkip to false.

For help on the properties and methods, use the automatic tooltips in B4A or inspect the source code.

Demo code
I've attached a demo app that lets you play with all of the properties and see the tips in action.

Compatibility:
Works with B4A 4.3+. Not sure about earlier versions.
Tested on Android 4.x and later, on various phones and tablets.

Not yet implemented:
- auto-size buttons to text
- add animated transitions between tips
- change string parameters to CSBuilder
- make this a customView?

Usage:
- Creative Commons Attribution license
(You can do whatever you like with this, as long as you credit me as the creator.)

Thanks to:
- @Erel for the GetARGB code (and lots more besides)
- @klaus for the drawRoundRect code
- @thedesolatesoul for porting MSShowTips, which wasn't quite what I needed, but motivated me to give it a go myself. :)
- @stevel05 for the GetRelativeLeft and GetRelativeTop code

Questions, suggestions, bugs? Please post in this thread.

Thanks!

sample tip 2.png
sample tip 3.png
sample tip 1.png
 

Attachments

  • DOTips.bas
    55.5 KB · Views: 143
  • DOTips-demo.zip
    289.1 KB · Views: 147
Last edited:

Dave O

Well-Known Member
Licensed User
Longtime User
Hi all, I've uploaded version 2.2:

- added option to remove Skip button
- added true/false argument to Hide so you can suppress the OnHide event if needed (in most cases, just replace hide with hide(true))
- fixed spacing under buttons
 

Dave O

Well-Known Member
Licensed User
Longtime User
Hi all, I've uploaded version 2.4:

- fixed a positioning bug in addTipForArea when inside a scrollview
- fixed OnHide signature so it auto-completes properly
 

Lello1964

Well-Known Member
Licensed User
Longtime User
Hello Dave, thanks for share your class.

I don't see how back to previus tips. ??
 

Dave O

Well-Known Member
Licensed User
Longtime User
There's no current way to go back to previous tips, although that would be easy to add. The main challenge would be making room for a third button (or moving the Skip button to a small close icon at the upper right, and putting Previous where Skip was). I'll give that some thought.
 

Lello1964

Well-Known Member
Licensed User
Longtime User
There's no current way to go back to previous tips, although that would be easy to add. The main challenge would be making room for a third button (or moving the Skip button to a small close icon at the upper right, and putting Previous where Skip was). I'll give that some thought.
I think it would be useful.
 

Dave O

Well-Known Member
Licensed User
Longtime User
Can we use this class cross platform?

Short answer: not yet, but shouldn't be hard for someone to port.

I haven't had the time (or need) to do any cross-platform apps yet, and haven't looked into what's involved in making a class/library/app work on other platforms, so I don't expect to create a cross-platform version of DOTips any time soon.

However, for someone who knows more about cross-platform stuff, this would probably be an easy class to port over. It uses basic controls (panels, labels, etc.) and most of the code deals with layout, which should be pretty portable. Also, the class only uses a few basic libraries - nothing exotic.
 

SMOOTSARA

Active Member
Licensed User
Longtime User
Hi dear friend (Dave O) šŸŒ¹
Thank you for the very useful and open source modulešŸ™

How can I set the text Gravity (Gravity.RIGHT) for Titel and Description to RIGHT ?

Thanks.
 

Dave O

Well-Known Member
Licensed User
Longtime User
Hi all, I've updated this class to v2.6. See the updated files in the first post.

The only change is to better handle the system font size (which the user can change from normal to much smaller or (more commonly) much larger).

The new version of DOTips automatically compensates for these system font-size changes by only changing the tips' text size slightly, so that:
- A very small system font size only makes the tip size slightly smaller than normal.
- A very large system font size only makes the tip size slightly larger than normal.

This should make it easier for us as developers to make tips appear as we designed, regardless of the system font size in play.

Cheers!
 

Dave O

Well-Known Member
Licensed User
Longtime User
Hi all, I've updated this class to v2.7. See the updated files in the first post.

The only change is to fix a crash on showing tips for views on certain versions of Android (e.g. Android 11 Go Edition). The GetRelativeLeft and GetRelativeTop subs (from @stevel05) were missing a Try clause for some reason, so I reverted to his original code.
 

asales

Expert
Licensed User
Longtime User
I tried to use this classe in a b4xpage, but I get this error:
B4X:
dotips_vvvvvvvvvvv0 (java line: 1779)
java.lang.IllegalArgumentException: width and height must be > 0
    at android.graphics.Bitmap.createBitmap(Bitmap.java:1113)
    at android.graphics.Bitmap.createBitmap(Bitmap.java:1080)
    at android.graphics.Bitmap.createBitmap(Bitmap.java:1030)
    at android.graphics.Bitmap.createBitmap(Bitmap.java:991)
    at anywheresoftware.b4a.objects.drawable.CanvasWrapper.Initialize(CanvasWrapper.java:81)
    at b4a.example.dotips2.dotips._vvvvvvvvvvv0(dotips.java:1779)
    at b4a.example.dotips2.dotips._vvvvvvvvvvvvvvv5(dotips.java:2190)
    at b4a.example.dotips2.page2._b4xpage_created(page2.java:54)
    at b4a.example.dotips2.page2.callSub(page2.java:89)
    at anywheresoftware.b4a.keywords.Common.CallSub4(Common.java:1098)
    at anywheresoftware.b4a.keywords.Common.CallSubNew2(Common.java:1069)
    at b4a.example.dotips2.b4xpagesmanager._vvvvvvvvvvvvvvvvvvvvvvvvvvvvvv0(b4xpagesmanager.java:528)
    at b4a.example.dotips2.b4xpagesmanager._vvv3(b4xpagesmanager.java:865)
This is the code:
B4X:
Private Sub B4XPage_Created (Root1 As B4XView)
    Root = Root1
    Root.LoadLayout("layout2")
    
    tips.Initialize(Me, Root, "tips")
    tips.addTipForView(Button1, "Position", "You can change most of the look and feel to suit your app.")
    tips.show
End Sub

The project is attached.

I'm doing some wrong?
Thanks in advance for any tips.
 

Attachments

  • dotips_b4xpages.zip
    27.4 KB · Views: 17

asales

Expert
Licensed User
Longtime User
I tried to use this classe in a b4xpage, but I get this error
I think that I fixed with change this lines:
B4X:
Dim xui As XUI

Public Sub Initialize(objectArg As Object, activityArg As B4XView, eventPrefixArg As String)
    callbackObject = objectArg
    
    tipActivity = xui.CreatePanel("tipActivity")
    tipActivity = activityArg
    
    (...)
End Sub
 

Dave O

Well-Known Member
Licensed User
Longtime User
Hi @asales , thanks for reporting this. I haven't tried B4XPages yet (have just been using standard Android activities), so I don't have any advice about adapting DOTips to it, but it looks like you may have already solved this with the code above? That will be useful for others who are using B4XPages - thanks again!
 
Top