ExploreByTouchHelper

abstract class ExploreByTouchHelper : AccessibilityDelegateCompat


ExploreByTouchHelper is a utility class for implementing accessibility support in custom Views that represent a collection of View-like logical items. It extends AccessibilityNodeProviderCompat and simplifies many aspects of providing information to accessibility services and managing accessibility focus.

Clients should override abstract methods on this class and attach it to the host view using setAccessibilityDelegate.

The host view should also override the events in the following code snippet so that the view's logical items are detected properly by the framework:

class MyCustomView extends View {
    private MyExploreByTouchHelper mExploreByTouchHelper;

    public MyCustomView(Context context, ...) {
        ...
        mExploreByTouchHelper = new MyExploreByTouchHelper(this);
        ViewCompat.setAccessibilityDelegate(this, mExploreByTouchHelper);
    }

    @Override
    public boolean dispatchHoverEvent(MotionEvent event) {
      return mHelper.dispatchHoverEvent(this, event)
          || super.dispatchHoverEvent(event);
    }

    @Override
    public boolean dispatchKeyEvent(KeyEvent event) {
      return mHelper.dispatchKeyEvent(event)
          || super.dispatchKeyEvent(event);
    }

    @Override
    public void onFocusChanged(boolean gainFocus, int direction,
        Rect previouslyFocusedRect) {
      super.onFocusChanged(gainFocus, direction, previouslyFocusedRect);
      mHelper.onFocusChanged(gainFocus, direction, previouslyFocusedRect);
    }
}

Summary

Constants

const Int
HOST_ID = -1

Virtual node identifier value for the host view's node.

const Int
INVALID_ID = -2147483648

Virtual node identifier value for invalid nodes.

Public constructors

Constructs a new helper that can expose a virtual view hierarchy for the specified host view.

Public functions

Boolean

Attempts to clear keyboard focus from a virtual view.

Boolean

Delegates hover events from the host view.

Boolean

Delegates key events from the host view.

Int
AccessibilityNodeProviderCompat!

Gets the provider for managing a virtual view hierarchy rooted at this View and reported to AccessibilityServices that explore the window content.

Int

This function is deprecated.

Use getAccessibilityFocusedVirtualViewId.

Int
Unit

Notifies the accessibility framework that the properties of the parent view have changed.

Unit
invalidateVirtualView(virtualViewId: Int)

Notifies the accessibility framework that the properties of a particular item have changed.

Unit
invalidateVirtualView(virtualViewId: Int, changeTypes: Int)

Notifies the accessibility framework that the properties of a particular item have changed.

Unit
onFocusChanged(
    gainFocus: Boolean,
    direction: Int,
    previouslyFocusedRect: Rect?
)

Delegates focus changes from the host view.

Unit

Initializes an AccessibilityEvent with information about the the host View which is the event source.

Unit

Initializes an AccessibilityNodeInfoCompat with information about the host view.

Boolean

Attempts to give keyboard focus to a virtual view.

Boolean
sendEventForVirtualView(virtualViewId: Int, eventType: Int)

Populates an event of the specified type with information about an item and attempts to send it up through the view hierarchy.

Unit

Calculates and assigns screen-relative bounds based on bounds in parent.

Protected functions

abstract Int

Provides a mapping between view-relative coordinates and logical items.

abstract Unit
getVisibleVirtualViews(virtualViewIds: (Mutable)List<Int!>!)

Populates a list with the view's visible items.

abstract Boolean
onPerformActionForVirtualView(
    virtualViewId: Int,
    action: Int,
    arguments: Bundle?
)

Performs the specified accessibility action on the item associated with the virtual view identifier.

Unit

Populates an AccessibilityEvent with information about the host view.

Unit
onPopulateEventForVirtualView(
    virtualViewId: Int,
    event: AccessibilityEvent
)

Populates an AccessibilityEvent with information about the specified item.

Unit

Populates an AccessibilityNodeInfoCompat with information about the host view.

abstract Unit
onPopulateNodeForVirtualView(
    virtualViewId: Int,
    node: AccessibilityNodeInfoCompat
)

Populates an AccessibilityNodeInfoCompat with information about the specified item.

Unit
onVirtualViewKeyboardFocusChanged(virtualViewId: Int, hasFocus: Boolean)

Called when the focus state of a virtual view changes.

Inherited functions

From androidx.core.view.AccessibilityDelegateCompat
Boolean

Dispatches an AccessibilityEvent to the host View first and then to its children for adding their text content to the event.

Unit

Gives a chance to the host View to populate the accessibility event with its text content.

Boolean
onRequestSendAccessibilityEvent(
    host: ViewGroup,
    child: View,
    event: AccessibilityEvent
)

Called when a child of the host View has requested sending an AccessibilityEvent and gives an opportunity to the parent (the host) to augment the event.

Boolean
performAccessibilityAction(host: View, action: Int, args: Bundle?)

Performs the specified accessibility action on the view.

Unit
sendAccessibilityEvent(host: View, eventType: Int)

Sends an accessibility event of the given type.

Unit

Sends an accessibility event.

Constants

HOST_ID

Added in 1.0.0
const val HOST_ID = -1: Int

Virtual node identifier value for the host view's node.

INVALID_ID

Added in 1.0.0
const val INVALID_ID = -2147483648: Int

Virtual node identifier value for invalid nodes.

Public constructors

ExploreByTouchHelper

Added in 1.0.0
ExploreByTouchHelper(host: View)

Constructs a new helper that can expose a virtual view hierarchy for the specified host view.

Parameters
host: View

view whose virtual view hierarchy is exposed by this helper

Public functions

clearKeyboardFocusForVirtualView

Added in 1.0.0
fun clearKeyboardFocusForVirtualView(virtualViewId: Int): Boolean

Attempts to clear keyboard focus from a virtual view.

Parameters
virtualViewId: Int

the identifier of the virtual view from which to clear keyboard focus

Returns
Boolean

whether this virtual view actually cleared keyboard focus

dispatchHoverEvent

Added in 1.0.0
fun dispatchHoverEvent(event: MotionEvent): Boolean

Delegates hover events from the host view.

Dispatches hover MotionEvents to the virtual view hierarchy when the Explore by Touch feature is enabled.

This method should be called by overriding the host view's dispatchHoverEvent method:

@Override
public boolean dispatchHoverEvent(MotionEvent event) {
  return mHelper.dispatchHoverEvent(this, event)
      || super.dispatchHoverEvent(event);
}
Parameters
event: MotionEvent

The hover event to dispatch to the virtual view hierarchy.

Returns
Boolean

Whether the hover event was handled.

dispatchKeyEvent

Added in 1.0.0
fun dispatchKeyEvent(event: KeyEvent): Boolean

Delegates key events from the host view.

This method should be called by overriding the host view's dispatchKeyEvent method:

@Override
public boolean dispatchKeyEvent(KeyEvent event) {
  return mHelper.dispatchKeyEvent(event)
      || super.dispatchKeyEvent(event);
}

getAccessibilityFocusedVirtualViewId

Added in 1.0.0
fun getAccessibilityFocusedVirtualViewId(): Int
Returns
Int

the identifier of the virtual view that has accessibility focus or INVALID_ID if no virtual view has accessibility focus

getAccessibilityNodeProvider

fun getAccessibilityNodeProvider(host: View!): AccessibilityNodeProviderCompat!

Gets the provider for managing a virtual view hierarchy rooted at this View and reported to AccessibilityServices that explore the window content.

The default implementation behaves as ViewCompat#getAccessibilityNodeProvider(View) for the case of no accessibility delegate been set.

Returns
AccessibilityNodeProviderCompat!

The provider.

getFocusedVirtualView

Added in 1.0.0
Deprecated in 1.0.0
fun getFocusedVirtualView(): Int

Returns the virtual view ID for the currently accessibility focused item.

Returns
Int

the identifier of the virtual view that has accessibility focus or INVALID_ID if no virtual view has accessibility focus

getKeyboardFocusedVirtualViewId

Added in 1.0.0
fun getKeyboardFocusedVirtualViewId(): Int
Returns
Int

the identifier of the virtual view that has keyboard focus or INVALID_ID if no virtual view has keyboard focus

invalidateRoot

Added in 1.0.0
fun invalidateRoot(): Unit

Notifies the accessibility framework that the properties of the parent view have changed.

You must call this method after adding or removing items from the parent view.

invalidateVirtualView

Added in 1.0.0
fun invalidateVirtualView(virtualViewId: Int): Unit

Notifies the accessibility framework that the properties of a particular item have changed.

You must call this method after changing any of the properties set in onPopulateNodeForVirtualView.

Parameters
virtualViewId: Int

the virtual view id to invalidate, or HOST_ID to invalidate the root view

invalidateVirtualView

Added in 1.0.0
fun invalidateVirtualView(virtualViewId: Int, changeTypes: Int): Unit

Notifies the accessibility framework that the properties of a particular item have changed.

You must call this method after changing any of the properties set in onPopulateNodeForVirtualView.

Parameters
virtualViewId: Int

the virtual view id to invalidate, or HOST_ID to invalidate the root view

changeTypes: Int

the bit mask of change types. May be 0 for the default (undefined) change type or one or more of:

onFocusChanged

Added in 1.0.0
fun onFocusChanged(
    gainFocus: Boolean,
    direction: Int,
    previouslyFocusedRect: Rect?
): Unit

Delegates focus changes from the host view.

This method should be called by overriding the host view's onFocusChanged method:

@Override
public boolean onFocusChanged(boolean gainFocus, int direction,
    Rect previouslyFocusedRect) {
  super.onFocusChanged(gainFocus, direction, previouslyFocusedRect);
  mHelper.onFocusChanged(gainFocus, direction, previouslyFocusedRect);
}

onInitializeAccessibilityEvent

fun onInitializeAccessibilityEvent(host: View!, event: AccessibilityEvent!): Unit

Initializes an AccessibilityEvent with information about the the host View which is the event source.

The default implementation behaves as ViewCompat#onInitalizeAccessibilityEvent(View v, AccessibilityEvent event) for the case of no accessibility delegate been set.

Parameters
host: View!

The View hosting the delegate.

event: AccessibilityEvent!

The event to initialize.

See also
onInitializeAccessibilityEvent

ViewCompat#onInitializeAccessibilityEvent(View, AccessibilityEvent)

onInitializeAccessibilityNodeInfo

fun onInitializeAccessibilityNodeInfo(
    host: View!,
    info: AccessibilityNodeInfoCompat!
): Unit

Initializes an AccessibilityNodeInfoCompat with information about the host view.

The default implementation behaves as ViewCompat#onInitializeAccessibilityNodeInfo(View, AccessibilityNodeInfoCompat) for the case of no accessibility delegate been set.

Parameters
host: View!

The View hosting the delegate.

info: AccessibilityNodeInfoCompat!

The instance to initialize.

See also
onInitializeAccessibilityNodeInfo

ViewCompat#onInitializeAccessibilityNodeInfo(View, AccessibilityNodeInfoCompat)

requestKeyboardFocusForVirtualView

Added in 1.0.0
fun requestKeyboardFocusForVirtualView(virtualViewId: Int): Boolean

Attempts to give keyboard focus to a virtual view.

Parameters
virtualViewId: Int

the identifier of the virtual view on which to place keyboard focus

Returns
Boolean

whether this virtual view actually took keyboard focus

sendEventForVirtualView

Added in 1.0.0
fun sendEventForVirtualView(virtualViewId: Int, eventType: Int): Boolean

Populates an event of the specified type with information about an item and attempts to send it up through the view hierarchy.

You should call this method after performing a user action that normally fires an accessibility event, such as clicking on an item.

public void performItemClick(T item) {
  ...
  sendEventForVirtualViewId(item.id, AccessibilityEvent.TYPE_VIEW_CLICKED);
}
Parameters
virtualViewId: Int

the identifier of the virtual view for which to send an event

eventType: Int

the type of event to send

Returns
Boolean

true if the event was sent successfully, false otherwise

setBoundsInScreenFromBoundsInParent

Added in 1.2.0-alpha03
fun setBoundsInScreenFromBoundsInParent(
    node: AccessibilityNodeInfoCompat,
    boundsInParent: Rect
): Unit

Calculates and assigns screen-relative bounds based on bounds in parent. Instead of calling the deprecated setBoundsInParent, it provides a convenient method to calculate and assign setBoundsInScreen based on boundsInParent.

Parameters
node: AccessibilityNodeInfoCompat

The node to populate

boundsInParent: Rect

The node bounds in the viewParent's coordinates.

Protected functions

getVirtualViewAt

Added in 1.0.0
protected abstract fun getVirtualViewAt(x: Float, y: Float): Int

Provides a mapping between view-relative coordinates and logical items.

Parameters
x: Float

The view-relative x coordinate

y: Float

The view-relative y coordinate

Returns
Int

virtual view identifier for the logical item under coordinates (x,y) or HOST_ID if there is no item at the given coordinates

getVisibleVirtualViews

Added in 1.0.0
protected abstract fun getVisibleVirtualViews(virtualViewIds: (Mutable)List<Int!>!): Unit

Populates a list with the view's visible items. The ordering of items within virtualViewIds specifies order of accessibility focus traversal.

Parameters
virtualViewIds: (Mutable)List<Int!>!

The list to populate with visible items

onPerformActionForVirtualView

Added in 1.0.0
protected abstract fun onPerformActionForVirtualView(
    virtualViewId: Int,
    action: Int,
    arguments: Bundle?
): Boolean

Performs the specified accessibility action on the item associated with the virtual view identifier. See performAction for more information.

Implementations must handle any actions added manually in onPopulateNodeForVirtualView.

The helper class automatically handles focus management resulting from ACTION_ACCESSIBILITY_FOCUS and ACTION_CLEAR_ACCESSIBILITY_FOCUS actions.

Parameters
virtualViewId: Int

The virtual view identifier of the item on which to perform the action

action: Int

The accessibility action to perform

arguments: Bundle?

(Optional) A bundle with additional arguments, or null

Returns
Boolean

true if the action was performed

onPopulateEventForHost

Added in 1.0.0
protected fun onPopulateEventForHost(event: AccessibilityEvent): Unit

Populates an AccessibilityEvent with information about the host view.

The default implementation is a no-op.

Parameters
event: AccessibilityEvent

the event to populate with information about the host view

onPopulateEventForVirtualView

Added in 1.0.0
protected fun onPopulateEventForVirtualView(
    virtualViewId: Int,
    event: AccessibilityEvent
): Unit

Populates an AccessibilityEvent with information about the specified item.

The helper class automatically populates the following fields based on the values set by onPopulateNodeForVirtualView, but implementations may optionally override them:

The following required fields are automatically populated by the helper class and may not be overridden:

Parameters
virtualViewId: Int

The virtual view id for the item for which to populate the event

event: AccessibilityEvent

The event to populate

onPopulateNodeForHost

Added in 1.0.0
protected fun onPopulateNodeForHost(node: AccessibilityNodeInfoCompat): Unit

Populates an AccessibilityNodeInfoCompat with information about the host view.

The default implementation is a no-op.

Parameters
node: AccessibilityNodeInfoCompat

the node to populate with information about the host view

onPopulateNodeForVirtualView

Added in 1.0.0
protected abstract fun onPopulateNodeForVirtualView(
    virtualViewId: Int,
    node: AccessibilityNodeInfoCompat
): Unit

Populates an AccessibilityNodeInfoCompat with information about the specified item.

Implementations must populate the following required fields:

The helper class automatically populates the following fields with default values, but implementations may optionally override them:

The following required fields are automatically populated by the helper class and may not be overridden:

Additionally, the helper class automatically handles keyboard focus and accessibility focus management by adding the appropriate ACTION_FOCUS, ACTION_CLEAR_FOCUS, ACTION_ACCESSIBILITY_FOCUS, or ACTION_CLEAR_ACCESSIBILITY_FOCUS actions. Implementations must never manually add these actions.

The helper class also automatically modifies parent- and screen-relative bounds to reflect the portion of the item visible within its parent.

Parameters
virtualViewId: Int

The virtual view identifier of the item for which to populate the node

node: AccessibilityNodeInfoCompat

The node to populate

onVirtualViewKeyboardFocusChanged

Added in 1.0.0
protected fun onVirtualViewKeyboardFocusChanged(virtualViewId: Int, hasFocus: Boolean): Unit

Called when the focus state of a virtual view changes.

Parameters
virtualViewId: Int

the virtual view identifier

hasFocus: Boolean

true if the view has focus, false otherwise