Register now for Android Dev Summit 2019!

ExploreByTouchHelper

abstract class ExploreByTouchHelper : AccessibilityDelegateCompat
kotlin.Any
   ↳ androidx.core.view.AccessibilityDelegateCompat
   ↳ androidx.customview.widget.ExploreByTouchHelper

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 ViewCompat#setAccessibilityDelegate:

class MyCustomView extends View {
      private MyVirtualViewHelper mVirtualViewHelper;
 
      public MyCustomView(Context context, ...) {
          ...
          mVirtualViewHelper = new MyVirtualViewHelper(this);
          ViewCompat.setAccessibilityDelegate(this, mVirtualViewHelper);
      }
 
      @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 boolean onFocusChanged(boolean gainFocus, int direction,
          Rect previouslyFocusedRect) {
        super.onFocusChanged(gainFocus, direction, previouslyFocusedRect);
        mHelper.onFocusChanged(gainFocus, direction, previouslyFocusedRect);
      }
  }
  mAccessHelper = new MyExploreByTouchHelper(someView);
  ViewCompat.setAccessibilityDelegate(someView, mAccessHelper);
  

Summary

Constants

static Int

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

static Int

Virtual node identifier value for invalid nodes.

Public constructors

<init>(@NonNull host: View)

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

Public methods

Boolean

Attempts to clear keyboard focus from a virtual view.

Boolean

Delegates hover events from the host view.

Boolean
dispatchKeyEvent(@NonNull event: KeyEvent)

Delegates key events from the host view.

Int

open AccessibilityNodeProviderCompat!

open Int

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

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, @Nullable previouslyFocusedRect: Rect?)

Delegates focus changes from the host view.

open Unit

open Unit

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.

Protected methods

abstract Int

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

abstract Unit

Populates a list with the view's visible items.

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

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

open Unit

Populates an AccessibilityEvent with information about the host view.

open Unit
onPopulateEventForVirtualView(virtualViewId: Int, @NonNull event: AccessibilityEvent)

Populates an AccessibilityEvent with information about the specified item.

open Unit

Populates an AccessibilityNodeInfoCompat with information about the host view.

abstract Unit

Populates an AccessibilityNodeInfoCompat with information about the specified item.

open Unit
onVirtualViewKeyboardFocusChanged(virtualViewId: Int, hasFocus: Boolean)

Called when the focus state of a virtual view changes.

Inherited functions

Constants

HOST_ID

static val HOST_ID: Int

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

Value: View.NO_ID

INVALID_ID

static val INVALID_ID: Int

Virtual node identifier value for invalid nodes.

Value: Integer.MIN_VALUE

Public constructors

<init>

ExploreByTouchHelper(@NonNull 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 methods

clearKeyboardFocusForVirtualView

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
Return
Boolean: whether this virtual view actually cleared keyboard focus

dispatchHoverEvent

fun dispatchHoverEvent(@NonNull 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 View#dispatchHoverEvent(MotionEvent) 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.
Return
Boolean: Whether the hover event was handled.

dispatchKeyEvent

fun dispatchKeyEvent(@NonNull event: KeyEvent): Boolean

Delegates key events from the host view.

This method should be called by overriding the host view's View#dispatchKeyEvent(KeyEvent) method:

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

getAccessibilityFocusedVirtualViewId

fun getAccessibilityFocusedVirtualViewId(): Int
Return
Int: the identifier of the virtual view that has accessibility focus or INVALID_ID if no virtual view has accessibility focus

getAccessibilityNodeProvider

open fun getAccessibilityNodeProvider(host: View!): AccessibilityNodeProviderCompat!

getFocusedVirtualView

open fun getFocusedVirtualView(): Int

Deprecated: Use getAccessibilityFocusedVirtualViewId().

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

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

getKeyboardFocusedVirtualViewId

fun getKeyboardFocusedVirtualViewId(): Int
Return
Int: the identifier of the virtual view that has keyboard focus or INVALID_ID if no virtual view has keyboard focus

invalidateRoot

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

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(int, AccessibilityNodeInfoCompat).

Parameters
virtualViewId Int: the virtual view id to invalidate, or HOST_ID to invalidate the root view

invalidateVirtualView

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(int, AccessibilityNodeInfoCompat).

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

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

Delegates focus changes from the host view.

This method should be called by overriding the host view's View#onFocusChanged(boolean, int, Rect) method:

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

onInitializeAccessibilityEvent

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

onInitializeAccessibilityNodeInfo

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

requestKeyboardFocusForVirtualView

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
Return
Boolean: whether this virtual view actually took keyboard focus

sendEventForVirtualView

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
Return
Boolean: true if the event was sent successfully, false otherwise

Protected methods

getVirtualViewAt

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
Return
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

protected abstract fun getVisibleVirtualViews(virtualViewIds: MutableList<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 MutableList<Int!>!: The list to populate with visible items

onPerformActionForVirtualView

protected abstract fun onPerformActionForVirtualView(virtualViewId: Int, action: Int, @Nullable arguments: Bundle?): Boolean

Performs the specified accessibility action on the item associated with the virtual view identifier. See AccessibilityNodeInfoCompat#performAction(int, Bundle) for more information.

Implementations must handle any actions added manually in onPopulateNodeForVirtualView(int, AccessibilityNodeInfoCompat).

The helper class automatically handles focus management resulting from AccessibilityNodeInfoCompat#ACTION_ACCESSIBILITY_FOCUS and AccessibilityNodeInfoCompat#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 Int: (Optional) A bundle with additional arguments, or null
Return
Boolean: true if the action was performed

onPopulateEventForHost

protected open fun onPopulateEventForHost(@NonNull 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

protected open fun onPopulateEventForVirtualView(virtualViewId: Int, @NonNull 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(int, AccessibilityNodeInfoCompat), 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 Int: The event to populate

onPopulateNodeForHost

protected open fun onPopulateNodeForHost(@NonNull 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

protected abstract fun onPopulateNodeForVirtualView(virtualViewId: Int, @NonNull 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 AccessibilityNodeInfoCompat#ACTION_FOCUS, AccessibilityNodeInfoCompat#ACTION_CLEAR_FOCUS, AccessibilityNodeInfoCompat#ACTION_ACCESSIBILITY_FOCUS, or AccessibilityNodeInfoCompat#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 Int: The node to populate

onVirtualViewKeyboardFocusChanged

protected open 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 Int: true if the view has focus, false otherwise