B4A Class DOTips 2.6 - show an overlay for app tips

Class Module: DOTips
Author: Dave O'Brien
Code Version: 2.6
Last Mod: 4 July 2021

Changes in this version:

- Small system fonts don't affect text size.
- Large system fonts increase text size slightly.


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

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

Thanks!

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

Attachments

  • DOTips.bas
    53.7 KB · Views: 82
  • DOTips-demo.zip
    289 KB · Views: 76
Last edited:

Dave O

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

Dave O

Well-Known Member
Licensed 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
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
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
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
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!
 
Top