B4A Class DOTips 2.7 - show an overlay for app tips

Dave O · May 31, 2015

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!

Dave O · Nov 12, 2018

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 · Dec 24, 2018

Hi all,

I've uploaded version 2.3, a minor update that adds an elevation property that you can change to keep the tips panel on top (if you have views with elevations greater than 10).

Dave O · May 25, 2019

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 · May 26, 2019

Hello Dave, thanks for share your class.

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

Dave O · May 26, 2019

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 · May 26, 2019

Dave O said:
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 · Jul 15, 2019

Hi all, I've uploaded version 2.5:

- addTipForArea: fixed a crash when not in a scrollview

yiankos1 · Jul 16, 2019

Can we use this class cross platform?

Dave O · Jul 16, 2019

yiankos1 said:
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 · Apr 24, 2020

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 · Apr 25, 2020

You can set the alignment of text using PortraitAlign and LandscapeAlign.

Dave O · Jul 5, 2021

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 · Dec 2, 2022

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 · Feb 6, 2024

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.

asales · Feb 8, 2024

asales said:
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 · Feb 9, 2024

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!

B4A Class DOTips 2.7 - show an overlay for app tips

Attachments

Dave O

Well-Known Member

Dave O

Well-Known Member

Dave O

Well-Known Member

Lello1964

Well-Known Member

Dave O

Well-Known Member

Lello1964

Well-Known Member

Dave O

Well-Known Member

yiankos1

Well-Known Member

Dave O

Well-Known Member

SMOOTSARA

Active Member

Dave O

Well-Known Member

Dave O

Well-Known Member

Dave O

Well-Known Member

asales

Expert

Attachments

asales

Expert

Dave O

Well-Known Member

Similar Threads

B4A Class DOTips 2.7 - show an overlay for app tips

Attachments

Well-Known Member

Well-Known Member

Well-Known Member

Well-Known Member

Well-Known Member

Well-Known Member

Well-Known Member

Well-Known Member

Well-Known Member

Active Member

Well-Known Member

Well-Known Member

Well-Known Member

Expert

Attachments

Expert

Well-Known Member

Similar Threads

Privacy & Transparency

Privacy & Transparency