Feature/guided tour inside the reader interface

app/build.gradle

@@ -216,5 +216,7 @@ dependencies {
     annotationProcessor 'androidx.room:room-compiler:2.6.1' // For Java projects, replace with the correct version
     ksp 'androidx.room:room-compiler:2.6.1'
 
+    implementation("com.getkeepsafe.taptargetview:taptargetview:1.13.3")
+
     implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.1.21"))
 }

app/src/main/java/org/cis_india/wsreader/helpers/Preferencesutils.kt

@@ -40,6 +40,8 @@ class PreferenceUtil(context: Context) {
         // Temporary preference keys
         const val LIBRARY_ONBOARDING_BOOL = "show_library_onboarding"
         const val LIBRARY_SWIPE_TOOLTIP_BOOL = "show_library_tooltip"
+
+        const val READER_ONBOARDING_BOOL = "reader_onboarding_guide"
     }
 
     //

app/src/main/java/org/cis_india/wsreader/reader/EpubReaderFragment.kt

@@ -44,6 +44,10 @@ import androidx.core.view.ViewCompat
 import androidx.core.view.WindowInsetsCompat
 import androidx.core.view.updateLayoutParams
 import android.widget.FrameLayout
+import com.getkeepsafe.taptargetview.TapTarget
+import com.getkeepsafe.taptargetview.TapTargetSequence
+import com.getkeepsafe.taptargetview.TapTargetView
+import org.cis_india.wsreader.reader.preferences.MainPreferencesBottomSheetDialogFragment
 
 @OptIn(ExperimentalReadiumApi::class)
 class EpubReaderFragment : VisualReaderFragment() {
@@ -77,6 +81,7 @@ class EpubReaderFragment : VisualReaderFragment() {
                 listener = model,
                 configuration = EpubNavigatorFragment.Configuration {
                     // To customize the text selection menu.
+                    // text selection
                     selectionActionModeCallback = customSelectionActionModeCallback
 
                     // App assets which will be accessible from the EPUB resources.
@@ -254,6 +259,12 @@ class EpubReaderFragment : VisualReaderFragment() {
                         menuSearchView = actionView as SearchView
                     }
 
+                    if (!isTutorialStarted.value) {
+                        view.post {
+                            startMenuTutorial()
+                        }
+                    }
+
                     connectSearch()
                     if (!isSearchViewIconified) menuSearch.expandActionView()
                 }
@@ -275,6 +286,118 @@ class EpubReaderFragment : VisualReaderFragment() {
         )
     }
 
+    // start menu tap target
+    // show onboarding guide for reader menu
+    private fun startMenuTutorial() {
+        val activity = requireActivity()
+        val targets = mutableListOf<TapTarget>()
+
+        activity.findViewById<View>(R.id.search)?.let {
+            targets.add(TapTarget.forView(it, getString(R.string.tutorial_search_title), getString(R.string.tutorial_search_desc)))
+        }
+
+        activity.findViewById<View>(R.id.tts)?.let {
+            targets.add(TapTarget.forView(it, getString(R.string.tutorial_tts_title), getString(R.string.tutorial_tts_desc)))
+        }
+
+        activity.findViewById<View>(R.id.bookmark)?.let {
+            targets.add(TapTarget.forView(it, getString(R.string.tutorial_bookmark_title), getString(R.string.tutorial_bookmark_desc)))
+        }
+
+        activity.findViewById<View>(R.id.settings)?.let {
+            targets.add(TapTarget.forView(it, getString(R.string.tutorial_settings_title), getString(R.string.tutorial_settings_desc)))
+        }
+
+        activity.findViewById<View>(R.id.toc)?.let {
+            targets.add(TapTarget.forView(it, getString(R.string.tutorial_toc_title), getString(R.string.tutorial_toc_desc)))
+        }
+
+        if (targets.isNotEmpty()) {
+            TapTargetSequence(activity)
+                .targets(targets)
+                .listener(object : TapTargetSequence.Listener {
+                    override fun onSequenceFinish() {
+                        onMenuTutorialComplete()
+                    }
+
+                    override fun onSequenceStep(lastTarget: TapTarget?, targetClicked: Boolean) {
+                        // Optional: Runs after every single step
+                        if (targetClicked && lastTarget?.id() == R.id.settings) {
+                            // open settings form more guides
+//                            openSettings()
+                        }
+                    }
+
+                    override fun onSequenceCanceled(lastTarget: TapTarget?) {
+                        onReaderMenuboardingComplete()
+                    }
+                })
+                .start()
+        }
+    }
+
+
+    // show tap target for navigation i.e
+    // navigate next page, navigate previous page and toggle the menu.
+    private fun startTapTutorial() {
+        val activity = requireActivity()
+        val targets = mutableListOf<TapTarget>()
+
+        activity.findViewById<View>(R.id.touch_center)?.let {
+            targets.add(TapTarget.forView(it, getString(R.string.tutorial_menu_toggle_title), getString(R.string.tutorial_menu_toggle_desc)))
+        }
+
+        if (targets.isNotEmpty()) {
+            TapTargetSequence(activity)
+                .targets(targets)
+                .listener(object : TapTargetSequence.Listener {
+                    override fun onSequenceFinish() {
+                        onTapTutorialComplete()
+                    }
+
+                    override fun onSequenceStep(lastTarget: TapTarget?, targetClicked: Boolean) {
+                        // Optional: Runs after every single step
+                    }
+
+                    override fun onSequenceCanceled(lastTarget: TapTarget?) {
+                        onReaderMenuboardingComplete()
+                    }
+                })
+                .start()
+        }
+    }
+
+//    private fun openSettings() {
+//        MainPreferencesBottomSheetDialogFragment()
+//            .show(childFragmentManager, "Settings")
+//    }
+
+    private fun onMenuTutorialComplete() {
+        updateSystemUiVisibility()
+        startTapTutorial()
+    }
+
+    private fun onTapTutorialComplete() {
+        onReaderMenuboardingComplete()
+        startSelectionPromptTutorial()
+    }
+
+    private fun startSelectionPromptTutorial() {
+        val activity = requireActivity()
+        val centerView = activity.findViewById<View>(R.id.touch_center) ?: view
+
+        TapTargetView.showFor(activity,
+            TapTarget.forView(centerView, getString(R.string.tutorial_select_text_title), getString(R.string.tutorial_select_text_desc))
+                .cancelable(true)
+                .transparentTarget(true),
+            object : TapTargetView.Listener() {
+                override fun onTargetClick(view: TapTargetView?) {
+                    super.onTargetClick(view)
+                }
+            }
+        )
+    }
+
     /**
      * Will display margin labels next to page numbers in an EPUB publication with a `page-list`
      * navigation document.

app/src/main/java/org/cis_india/wsreader/reader/FullscreenReaderActivityDelegate.kt

@@ -51,7 +51,9 @@ class FullscreenReaderActivityDelegate(
         if (readerFragment.isHidden) {
             activity.showSystemUi()
         } else {
-            readerFragment.updateSystemUiVisibility()
+            if(readerFragment.isTutorialStarted.value){
+                readerFragment.updateSystemUiVisibility()
+            }
         }
 
         // Seems to be required to adjust padding when transitioning from the outlines to the screen reader

app/src/main/java/org/cis_india/wsreader/reader/VisualReaderFragment.kt

@@ -42,6 +42,8 @@ import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.systemBarsPadding
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.MutableState
+import androidx.compose.runtime.State
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.setValue
@@ -78,6 +80,7 @@ import org.readium.r2.shared.util.Language
 import org.cis_india.wsreader.R
 import org.cis_india.wsreader.data.model.Highlight
 import org.cis_india.wsreader.databinding.FragmentReaderBinding
+import org.cis_india.wsreader.helpers.PreferenceUtil
 import org.cis_india.wsreader.reader.tts.TtsControls
 import org.cis_india.wsreader.reader.tts.TtsPreferencesBottomSheetDialogFragment
 import org.cis_india.wsreader.reader.tts.TtsViewModel
@@ -101,6 +104,19 @@ abstract class VisualReaderFragment : BaseReaderFragment() {
 
     protected var binding: FragmentReaderBinding by viewLifecycle()
 
+
+
+    private val prefs by lazy { PreferenceUtil(requireContext()) }
+
+
+    private val _showMenuOnboardingTapTargets: MutableState<Boolean> by lazy {
+        mutableStateOf(
+            value = prefs.getBoolean(PreferenceUtil.READER_ONBOARDING_BOOL, false)
+        )
+    }
+
+    val isTutorialStarted: State<Boolean> get() = _showMenuOnboardingTapTargets
+
     private lateinit var navigatorFragment: Fragment
 
     override fun onCreateView(
@@ -117,6 +133,11 @@ abstract class VisualReaderFragment : BaseReaderFragment() {
      */
     private var disableTouches by mutableStateOf(false)
 
+    fun onReaderMenuboardingComplete() {
+        prefs.putBoolean(PreferenceUtil.READER_ONBOARDING_BOOL, true)
+        _showMenuOnboardingTapTargets.value = true
+    }
+
     override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
         super.onViewCreated(view, savedInstanceState)
 

app/src/main/res/layout/fragment_reader.xml

@@ -11,6 +11,21 @@
         android:layout_height="match_parent"
         />
 
+    <LinearLayout
+        android:layout_width="match_parent"
+        android:layout_height="match_parent"
+        android:orientation="horizontal"
+        android:baselineAligned="false">
+
+        <View
+            android:id="@+id/touch_center"
+            android:layout_width="0dp"
+            android:layout_height="match_parent"
+            android:layout_weight="1"
+            android:background="?attr/selectableItemBackground" />
+
+    </LinearLayout>
+
     <SeekBar
         android:id="@+id/readingProgressBar"
         android:layout_width="match_parent"

app/src/main/res/values/strings.xml

@@ -314,4 +314,28 @@
     <string name="link_sourcecode_repo">View GitHub Repo</string>
     <string name="link_sourcecode">GitHub</string>
     <string name="woops">Oops!</string>
+
+
+    // Reader tutorial guides
+
+    <string name="tutorial_search_title">Search</string>
+    <string name="tutorial_search_desc">Search through the book</string>
+
+    <string name="tutorial_tts_title">TTS</string>
+    <string name="tutorial_tts_desc">Text to speech, This helps read aloud the books</string>
+
+    <string name="tutorial_bookmark_title">Bookmark</string>
+    <string name="tutorial_bookmark_desc">Click to bookmark current position of the book for easier retrieval</string>
+
+    <string name="tutorial_settings_title">Settings</string>
+    <string name="tutorial_settings_desc">Configure preferences i.e language, fonts, scrolling and vertical text</string>
+
+    <string name="tutorial_toc_title">Book Navigation</string>
+    <string name="tutorial_toc_desc">This contains chapters and saved bookmarks</string>\
+
+    <string name="tutorial_menu_toggle_title">Open or Close Menu</string>
+    <string name="tutorial_menu_toggle_desc">Tap at the center of the screen to open or close menu</string>
+
+    <string name="tutorial_select_text_title">Select Text</string>
+    <string name="tutorial_select_text_desc">Long-press on any word to see the selection menu and tools i.e underline, highlight and add notes!</string>
 </resources>