ADFA-3127 | Support onHoverListener and tooltips for mouse interactions (#1120)

jatezzz · web-flow · commit ff9337edad6d · 2026-03-27T09:57:50.000-05:00
* feat: implement hover listeners and tooltip support for active elements
Added hover event handling to UI components and tooltips to action buttons

* fix: update import

* feat(tooltip): improve hover UX with delayed dismiss and hover guard

Add delayed dismiss logic to prevent tooltip flicker when moving cursor between anchor and popup.
Includes hover guard for tooltip content and enables ESC dismissal via focusable popup.
diff --git a/app/src/main/java/com/itsaky/androidide/activities/editor/EditorHandlerActivity.kt b/app/src/main/java/com/itsaky/androidide/activities/editor/EditorHandlerActivity.kt
@@ -432,6 +432,17 @@ open class EditorHandlerActivity :
 						tag = action.retrieveTooltipTag(false),
 					)
 				},
+				onHover = { anchor ->
+					TooltipManager.cancelScheduledDismiss()
+					TooltipManager.showIdeCategoryTooltip(
+						context = this@EditorHandlerActivity,
+						anchorView = anchor,
+						tag = action.retrieveTooltipTag(false)
+					)
+				},
+				onHoverExit = {
+					TooltipManager.scheduleActiveTooltipDismiss()
+				},
 				shouldAddMargin = !isLast,
 			)
 		}
diff --git a/app/src/main/java/com/itsaky/androidide/activities/editor/LandscapeImmersiveController.kt b/app/src/main/java/com/itsaky/androidide/activities/editor/LandscapeImmersiveController.kt
@@ -2,6 +2,7 @@ package com.itsaky.androidide.activities.editor
 
 import android.annotation.SuppressLint
 import android.content.res.Configuration
+import android.view.InputDevice
 import android.view.MotionEvent
 import android.view.View
 import android.view.View.OnLayoutChangeListener
@@ -122,6 +123,22 @@ class LandscapeImmersiveController(
         }
     }
 
+    /**
+     * Observes mouse hover events to manage the top bar's auto-hide behavior.
+     * It pauses the auto-hide timer while the cursor is over the bar (or its buttons),
+     * and resumes it when the cursor leaves.
+     */
+    private val topBarHoverObserver: (MotionEvent) -> Unit = { event ->
+        if (event.isFromSource(InputDevice.SOURCE_MOUSE)) {
+            when (event.actionMasked) {
+                MotionEvent.ACTION_HOVER_ENTER,
+                MotionEvent.ACTION_HOVER_MOVE -> onTopBarInteractionStarted()
+
+                MotionEvent.ACTION_HOVER_EXIT -> onTopBarInteractionEnded()
+            }
+        }
+    }
+
     @SuppressLint("ClickableViewAccessibility")
     fun bind() {
         if (isBound) return
@@ -131,6 +148,7 @@ class LandscapeImmersiveController(
         appBarContent.addOnLayoutChangeListener(appBarLayoutChangeListener)
         bottomSheetBehavior.addBottomSheetCallback(bottomSheetCallback)
         appBarContent.onTouchEventObserved = topBarTouchObserver
+        appBarContent.onHoverEventObserved = topBarHoverObserver
     }
 
     fun onPause() {
@@ -166,6 +184,7 @@ class LandscapeImmersiveController(
         appBarContent.removeOnLayoutChangeListener(appBarLayoutChangeListener)
         bottomSheetBehavior.removeBottomSheetCallback(bottomSheetCallback)
         appBarContent.onTouchEventObserved = null
+        appBarContent.onHoverEventObserved = null
     }
 
     fun onConfigurationChanged(newConfig: Configuration) {
diff --git a/app/src/main/res/layout-land/fragment_saved_projects.xml b/app/src/main/res/layout-land/fragment_saved_projects.xml
@@ -52,6 +52,7 @@
                     android:layout_height="wrap_content"
                     android:minWidth="0dp"
                     android:layout_marginEnd="2dp"
+                    android:tooltipText="@string/exit"
                     android:text="@string/exit" />
 
                 <View
@@ -64,6 +65,7 @@
                     android:layout_width="wrap_content"
                     android:layout_height="wrap_content"
                     android:minWidth="0dp"
+                    android:tooltipText="@string/new_project"
                     android:text="@string/new_project" />
             </LinearLayout>
 
@@ -72,6 +74,7 @@
                 style="@style/Widget.Material3.Button.TextButton"
                 android:layout_width="match_parent"
                 android:layout_height="wrap_content"
+                android:tooltipText="@string/open_from_folder"
                 android:text="@string/open_from_folder" />
         </LinearLayout>
 
diff --git a/app/src/main/res/layout/layout_project_filters_bar.xml b/app/src/main/res/layout/layout_project_filters_bar.xml
@@ -31,5 +31,6 @@
         android:layout_width="wrap_content"
         android:layout_height="wrap_content"
         android:layout_marginStart="6dp"
+        android:tooltipText="@string/sort_projects_label"
         app:icon="@drawable/ic_sort" />
 </LinearLayout>
diff --git a/app/src/main/res/layout/layout_project_filters_sheet.xml b/app/src/main/res/layout/layout_project_filters_sheet.xml
@@ -40,11 +40,12 @@
         </com.google.android.material.textfield.TextInputLayout>
         <com.google.android.material.button.MaterialButton
             android:id="@+id/sort_toggle_btn"
-            style="@style/Widget.Material3.Button.OutlinedButton.Icon"
-            android:backgroundTint="@color/_blue_wave_light_colorPrimaryDark"
+            style="@style/Widget.Material3.Button.IconButton.Filled"
             android:layout_width="50dp"
-            android:layout_height="match_parent"
+            android:layout_height="wrap_content"
             android:layout_marginStart="12dp"
+            android:tooltipText="@string/toggle_sorting"
+            android:contentDescription="@string/toggle_sorting"
             app:icon="@drawable/ic_arrow_up"
             app:iconTint="@android:color/primary_text_dark" />
     </LinearLayout>
@@ -67,13 +68,13 @@
             android:layout_marginEnd="12dp"
             android:visibility="gone"
             android:text="@string/reset_sorting"
+            android:tooltipText="@string/reset_sorting"
             app:iconTint="@color/white"
             app:icon="@drawable/ic_close" />
 
         <com.google.android.material.button.MaterialButton
             android:id="@+id/apply_filters_btn"
-            style="@style/Widget.Material3.Button.TextButton.Dialog"
-            android:backgroundTint="@color/_blue_wave_light_colorPrimaryDark"
+            android:tooltipText="@string/apply_sorting"
             android:textColor="@android:color/white"
             android:layout_width="0dp"
             android:layout_weight="1"
diff --git a/common/src/main/java/com/itsaky/androidide/ui/ProjectActionsToolbar.kt b/common/src/main/java/com/itsaky/androidide/ui/ProjectActionsToolbar.kt
@@ -4,7 +4,9 @@ import android.content.Context
 import android.graphics.drawable.Drawable
 import android.util.AttributeSet
 import android.util.TypedValue
+import android.view.InputDevice
 import android.view.LayoutInflater
+import android.view.MotionEvent
 import android.view.View
 import android.widget.ImageButton
 import android.widget.LinearLayout
@@ -36,10 +38,14 @@ class ProjectActionsToolbar @JvmOverloads constructor(
         hint: String,
         onClick: () -> Unit,
         onLongClick: () -> Unit,
+        onHover: ((View) -> Unit)? = null,
+        onHoverExit: (() -> Unit)? = null,
         shouldAddMargin: Boolean
     ) {
         val item = ImageButton(context).apply {
-            tooltipText = hint
+            if (onHover == null) {
+                tooltipText = hint
+            }
             contentDescription = hint
             setImageDrawable(icon)
             addCircleRipple()
@@ -57,6 +63,24 @@ class ProjectActionsToolbar @JvmOverloads constructor(
                 onLongClick()
                 true
             }
+            var hoverRunnable: Runnable? = null
+            setOnHoverListener { view, event ->
+                if (!event.isFromSource(InputDevice.SOURCE_MOUSE)) return@setOnHoverListener false
+
+                when (event.actionMasked) {
+                    MotionEvent.ACTION_HOVER_ENTER -> {
+                        hoverRunnable?.let { view.removeCallbacks(it) }
+                        hoverRunnable = Runnable { onHover?.invoke(view) }
+                        view.postDelayed(hoverRunnable, 600L)
+                    }
+                    MotionEvent.ACTION_HOVER_EXIT -> {
+                        hoverRunnable?.let { view.removeCallbacks(it) }
+                        onHoverExit?.invoke()
+                    }
+                }
+
+                false
+            }
         }
         binding.menuContainer.addView(item)
     }
diff --git a/common/src/main/java/com/itsaky/androidide/ui/TouchObservingLinearLayout.kt b/common/src/main/java/com/itsaky/androidide/ui/TouchObservingLinearLayout.kt
@@ -11,9 +11,15 @@ class TouchObservingLinearLayout @JvmOverloads constructor(
 ) : LinearLayout(context, attrs) {
 
     var onTouchEventObserved: ((MotionEvent) -> Unit)? = null
+    var onHoverEventObserved: ((MotionEvent) -> Unit)? = null
 
     override fun dispatchTouchEvent(ev: MotionEvent): Boolean {
         onTouchEventObserved?.invoke(ev)
         return super.dispatchTouchEvent(ev)
     }
+
+    override fun dispatchHoverEvent(event: MotionEvent): Boolean {
+        onHoverEventObserved?.invoke(event)
+        return super.dispatchHoverEvent(event)
+    }
 }
diff --git a/idetooltips/src/main/java/com/itsaky/androidide/idetooltips/ToolTipManager.kt b/idetooltips/src/main/java/com/itsaky/androidide/idetooltips/ToolTipManager.kt
@@ -22,6 +22,10 @@ import android.webkit.WebViewClient
 import android.widget.ImageButton
 import android.widget.PopupWindow
 import android.widget.TextView
+import android.os.Handler
+import android.os.Looper
+import android.view.InputDevice
+import android.view.MotionEvent
 import androidx.appcompat.app.AlertDialog
 import androidx.core.content.ContextCompat.getColor
 import com.itsaky.androidide.activities.editor.HelpActivity
@@ -41,6 +45,10 @@ import java.io.File
 
 object TooltipManager {
     private const val TAG = "TooltipManager"
+    private const val DEFAULT_HOVER_DISMISS_DELAY_MS = 800L
+    private var activePopupWindow: PopupWindow? = null
+    private val dismissHandler = Handler(Looper.getMainLooper())
+    private var pendingDismiss: Runnable? = null
     private val databaseTimestamp: Long = File(Environment.DOC_DB.absolutePath).lastModified()
     private val debugDatabaseFile: File = File(android.os.Environment.getExternalStorageDirectory().toString() +
             "/Download/documentation.db")
@@ -149,6 +157,27 @@ object TooltipManager {
         }
     }
 
+    fun dismissActiveTooltip() {
+        cancelScheduledDismiss()
+        activePopupWindow?.dismiss()
+        activePopupWindow = null
+    }
+
+    fun scheduleActiveTooltipDismiss(delayMs: Long = DEFAULT_HOVER_DISMISS_DELAY_MS) {
+        cancelScheduledDismiss()
+        val popup = activePopupWindow ?: return
+        pendingDismiss = Runnable {
+            if (activePopupWindow === popup) {
+                popup.dismiss()
+            }
+        }.also { dismissHandler.postDelayed(it, delayMs) }
+    }
+
+    fun cancelScheduledDismiss() {
+        pendingDismiss?.let { dismissHandler.removeCallbacks(it) }
+        pendingDismiss = null
+    }
+
     // Displays a tooltip for category [TooltipCategory.CATEGORY_IDE] in a particular context
     // (An Activity, Fragment, Dialog etc)
     fun showIdeCategoryTooltip(context: Context, anchorView: View, tag: String) {
@@ -355,6 +384,16 @@ object TooltipManager {
         popupWindow.setBackgroundDrawable(ColorDrawable(transparentColor))
         popupView.setBackgroundResource(R.drawable.idetooltip_popup_background)
 
+        dismissActiveTooltip()
+
+        activePopupWindow = popupWindow
+        popupWindow.setOnDismissListener {
+            cancelScheduledDismiss()
+            if (activePopupWindow === popupWindow) {
+                activePopupWindow = null
+            }
+        }
+
         popupWindow.isFocusable = true
         popupWindow.isOutsideTouchable = true
         if (anchorView.isInOverlayWindow()) {
@@ -391,6 +430,31 @@ object TooltipManager {
             }
             setColorFilter(iconTintColor)
         }
+
+        val hoverGuard: (MotionEvent) -> Unit = label@{ event ->
+            if (!event.isFromSource(InputDevice.SOURCE_MOUSE)) return@label
+            when (event.actionMasked) {
+                MotionEvent.ACTION_HOVER_ENTER,
+                MotionEvent.ACTION_HOVER_MOVE -> cancelScheduledDismiss()
+                MotionEvent.ACTION_HOVER_EXIT -> scheduleActiveTooltipDismiss()
+            }
+        }
+
+        val hoverListener = View.OnHoverListener { _, event ->
+            hoverGuard(event)
+            false
+        }
+
+        installHoverGuard(
+            hoverListener = hoverListener,
+            popupView = popupView,
+            webView = webView,
+            seeMore = seeMore,
+            infoButton = infoButton,
+            feedbackButton = feedbackButton,
+        )
+
+        cancelScheduledDismiss()
     }
 
     /**
@@ -508,4 +572,19 @@ object TooltipManager {
         popupWindow.showAtLocation(parentView, Gravity.NO_GRAVITY, x, y)
     }
 
+    private fun installHoverGuard(
+        hoverListener: View.OnHoverListener,
+        popupView: View,
+        webView: WebView,
+        seeMore: View,
+        infoButton: View,
+        feedbackButton: View,
+    ) {
+        popupView.setOnHoverListener(hoverListener)
+        webView.setOnHoverListener(hoverListener)
+        seeMore.setOnHoverListener(hoverListener)
+        infoButton.setOnHoverListener(hoverListener)
+        feedbackButton.setOnHoverListener(hoverListener)
+    }
+
 }
diff --git a/resources/src/main/res/values/strings.xml b/resources/src/main/res/values/strings.xml
@@ -145,6 +145,7 @@
 	<string name="save_and_close">Save files and close project</string>
 	<string name="search_projects_hint">Search projects by name…</string>
     <string name="sort_projects_label">Sort projects</string>
+    <string name="toggle_sorting">Toggle sorting</string>
     <string name="reset_sorting">Reset</string>
     <string name="apply_sorting">Sort</string>
     <string name="sort_by_hint">Sort by</string>

Original file line number	Diff line number	Diff line change
`@@ -432,6 +432,17 @@ open class EditorHandlerActivity :`
`432`	`432`	`tag = action.retrieveTooltipTag(false),`
`433`	`433`	`)`
`434`	`434`	`},`
	`435`	`+ onHover = { anchor ->`
	`436`	`+ TooltipManager.cancelScheduledDismiss()`
	`437`	`+ TooltipManager.showIdeCategoryTooltip(`
	`438`	`+ context = this@EditorHandlerActivity,`
	`439`	`+ anchorView = anchor,`
	`440`	`+ tag = action.retrieveTooltipTag(false)`
	`441`	`+ )`
	`442`	`+ },`
	`443`	`+ onHoverExit = {`
	`444`	`+ TooltipManager.scheduleActiveTooltipDismiss()`
	`445`	`+ },`
`435`	`446`	`shouldAddMargin = !isLast,`
`436`	`447`	`)`
`437`	`448`	`}`
Original file line number	Diff line number	Diff line change
`@@ -11,9 +11,15 @@ class TouchObservingLinearLayout @JvmOverloads constructor(`
`11`	`11`	`) : LinearLayout(context, attrs) {`
`12`	`12`
`13`	`13`	`var onTouchEventObserved: ((MotionEvent) -> Unit)? = null`
	`14`	`+ var onHoverEventObserved: ((MotionEvent) -> Unit)? = null`
`14`	`15`
`15`	`16`	`override fun dispatchTouchEvent(ev: MotionEvent): Boolean {`
`16`	`17`	`onTouchEventObserved?.invoke(ev)`
`17`	`18`	`return super.dispatchTouchEvent(ev)`
`18`	`19`	`}`
	`20`	`+`
	`21`	`+ override fun dispatchHoverEvent(event: MotionEvent): Boolean {`
	`22`	`+ onHoverEventObserved?.invoke(event)`
	`23`	`+ return super.dispatchHoverEvent(event)`
	`24`	`+ }`
`19`	`25`	`}`