ExploreByTouchHelper

Artifact: androidx.customview:customview

Added in 1.0.0

Kotlin |Java

public abstract class ExploreByTouchHelper extends AccessibilityDelegateCompat

java.lang.Object
↳	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 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
`static final int`	`HOST_ID = -1` Virtual node identifier value for the host view's node.
`static final int`	`INVALID_ID = -2147483648` Virtual node identifier value for invalid nodes.

Public constructors
`ExploreByTouchHelper(@NonNull View host)` Constructs a new helper that can expose a virtual view hierarchy for the specified host view.

Public methods
`final boolean`	`clearKeyboardFocusForVirtualView(int virtualViewId)` Attempts to clear keyboard focus from a virtual view.
`final boolean`	`dispatchHoverEvent(@NonNull MotionEvent event)` Delegates hover events from the host view.
`final boolean`	`dispatchKeyEvent(@NonNull KeyEvent event)` Delegates key events from the host view.
`final int`	`getAccessibilityFocusedVirtualViewId()`
`AccessibilityNodeProviderCompat`	`getAccessibilityNodeProvider(View host)` Gets the provider for managing a virtual view hierarchy rooted at this View and reported to `AccessibilityService`s that explore the window content.
`int`	`getFocusedVirtualView()` This method is deprecated. Use `getAccessibilityFocusedVirtualViewId`.
`final int`	`getKeyboardFocusedVirtualViewId()`
`final void`	`invalidateRoot()` Notifies the accessibility framework that the properties of the parent view have changed.
`final void`	`invalidateVirtualView(int virtualViewId)` Notifies the accessibility framework that the properties of a particular item have changed.
`final void`	`invalidateVirtualView(int virtualViewId, int changeTypes)` Notifies the accessibility framework that the properties of a particular item have changed.
`final void`	`onFocusChanged( boolean gainFocus, int direction, @Nullable Rect previouslyFocusedRect )` Delegates focus changes from the host view.
`void`	`onInitializeAccessibilityEvent(View host, AccessibilityEvent event)` Initializes an `AccessibilityEvent` with information about the the host View which is the event source.
`void`	`onInitializeAccessibilityNodeInfo( View host, AccessibilityNodeInfoCompat info )` Initializes an `AccessibilityNodeInfoCompat` with information about the host view.
`final boolean`	`requestKeyboardFocusForVirtualView(int virtualViewId)` Attempts to give keyboard focus to a virtual view.
`final boolean`	`sendEventForVirtualView(int virtualViewId, int eventType)` Populates an event of the specified type with information about an item and attempts to send it up through the view hierarchy.
`final void`	`setBoundsInScreenFromBoundsInParent( @NonNull AccessibilityNodeInfoCompat node, @NonNull Rect boundsInParent )` Calculates and assigns screen-relative bounds based on bounds in parent.

Protected methods
`abstract int`	`getVirtualViewAt(float x, float y)` Provides a mapping between view-relative coordinates and logical items.
`abstract void`	`getVisibleVirtualViews(List<Integer> virtualViewIds)` Populates a list with the view's visible items.
`abstract boolean`	`onPerformActionForVirtualView( int virtualViewId, int action, @Nullable Bundle arguments )` Performs the specified accessibility action on the item associated with the virtual view identifier.
`void`	`onPopulateEventForHost(@NonNull AccessibilityEvent event)` Populates an `AccessibilityEvent` with information about the host view.
`void`	`onPopulateEventForVirtualView( int virtualViewId, @NonNull AccessibilityEvent event )` Populates an `AccessibilityEvent` with information about the specified item.
`void`	`onPopulateNodeForHost(@NonNull AccessibilityNodeInfoCompat node)` Populates an `AccessibilityNodeInfoCompat` with information about the host view.
`abstract void`	`onPopulateNodeForVirtualView( int virtualViewId, @NonNull AccessibilityNodeInfoCompat node )` Populates an `AccessibilityNodeInfoCompat` with information about the specified item.
`void`	`onVirtualViewKeyboardFocusChanged(int virtualViewId, boolean hasFocus)` Called when the focus state of a virtual view changes.

Inherited methods

From androidx.core.view.AccessibilityDelegateCompat

`boolean`	`dispatchPopulateAccessibilityEvent( @NonNull View host, @NonNull AccessibilityEvent event )` Dispatches an `AccessibilityEvent` to the host `View` first and then to its children for adding their text content to the event.
`void`	`onPopulateAccessibilityEvent( @NonNull View host, @NonNull AccessibilityEvent event )` Gives a chance to the host View to populate the accessibility event with its text content.
`boolean`	`onRequestSendAccessibilityEvent( @NonNull ViewGroup host, @NonNull View child, @NonNull AccessibilityEvent event )` 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( @NonNull View host, int action, @Nullable Bundle args )` Performs the specified accessibility action on the view.
`void`	`sendAccessibilityEvent(@NonNull View host, int eventType)` Sends an accessibility event of the given type.
`void`	`sendAccessibilityEventUnchecked( @NonNull View host, @NonNull AccessibilityEvent event )` Sends an accessibility event.

Constants

HOST_ID

Added in 1.0.0

public static final int HOST_ID = -1

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

INVALID_ID

Added in 1.0.0

public static final int INVALID_ID = -2147483648

Virtual node identifier value for invalid nodes.

Public constructors

ExploreByTouchHelper

Added in 1.0.0

public ExploreByTouchHelper(@NonNull View host)

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

Parameters
`@NonNull View host`	view whose virtual view hierarchy is exposed by this helper

Public methods

clearKeyboardFocusForVirtualView

Added in 1.0.0

public final boolean clearKeyboardFocusForVirtualView(int virtualViewId)

Attempts to clear keyboard focus from a virtual view.

Parameters
`int virtualViewId`	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

public final boolean dispatchHoverEvent(@NonNull MotionEvent event)

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
`@NonNull MotionEvent event`	The hover event to dispatch to the virtual view hierarchy.

Returns
`boolean`	Whether the hover event was handled.

dispatchKeyEvent

Added in 1.0.0

public final boolean dispatchKeyEvent(@NonNull KeyEvent event)

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

public final int getAccessibilityFocusedVirtualViewId()

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

getAccessibilityNodeProvider

public AccessibilityNodeProviderCompat getAccessibilityNodeProvider(View host)

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.

See also
`AccessibilityNodeProviderCompat`

getFocusedVirtualView

Added in 1.0.0

Deprecated in 1.0.0

public int getFocusedVirtualView()

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

public final int getKeyboardFocusedVirtualViewId()

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

public final void invalidateRoot()

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

public final void invalidateVirtualView(int virtualViewId)

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
`int virtualViewId`	the virtual view id to invalidate, or `HOST_ID` to invalidate the root view

See also
`invalidateVirtualView`

invalidateVirtualView

Added in 1.0.0

public final void invalidateVirtualView(int virtualViewId, int changeTypes)

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

int virtualViewId

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

int changeTypes

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

public final void onFocusChanged(
    boolean gainFocus,
    int direction,
    @Nullable Rect previouslyFocusedRect
)

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

public void onInitializeAccessibilityEvent(View host, AccessibilityEvent event)

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
`View host`	The View hosting the delegate.
`AccessibilityEvent event`	The event to initialize.

See also
`onInitializeAccessibilityEvent`	ViewCompat#onInitializeAccessibilityEvent(View, AccessibilityEvent)

onInitializeAccessibilityNodeInfo

public void onInitializeAccessibilityNodeInfo(
    View host,
    AccessibilityNodeInfoCompat info
)

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
`View host`	The View hosting the delegate.
`AccessibilityNodeInfoCompat info`	The instance to initialize.

See also
`onInitializeAccessibilityNodeInfo`	ViewCompat#onInitializeAccessibilityNodeInfo(View, AccessibilityNodeInfoCompat)

requestKeyboardFocusForVirtualView

Added in 1.0.0

public final boolean requestKeyboardFocusForVirtualView(int virtualViewId)

Attempts to give keyboard focus to a virtual view.

Parameters
`int virtualViewId`	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

public final boolean sendEventForVirtualView(int virtualViewId, int eventType)

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
`int virtualViewId`	the identifier of the virtual view for which to send an event
`int eventType`	the type of event to send

Returns
`boolean`	`true` if the event was sent successfully, `false` otherwise

setBoundsInScreenFromBoundsInParent

Added in 1.2.0-alpha03

public final void setBoundsInScreenFromBoundsInParent(
    @NonNull AccessibilityNodeInfoCompat node,
    @NonNull Rect boundsInParent
)

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
`@NonNull AccessibilityNodeInfoCompat node`	The node to populate
`@NonNull Rect boundsInParent`	The node bounds in the viewParent's coordinates.

Protected methods

getVirtualViewAt

Added in 1.0.0

protected abstract int getVirtualViewAt(float x, float y)

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

Parameters
`float x`	The view-relative x coordinate
`float y`	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 void getVisibleVirtualViews(List<Integer> virtualViewIds)

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

Parameters
`List<Integer> virtualViewIds`	The list to populate with visible items

onPerformActionForVirtualView

Added in 1.0.0

protected abstract boolean onPerformActionForVirtualView(
    int virtualViewId,
    int action,
    @Nullable Bundle arguments
)

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
`int virtualViewId`	The virtual view identifier of the item on which to perform the action
`int action`	The accessibility action to perform
`@Nullable Bundle arguments`	(Optional) A bundle with additional arguments, or null

Returns
`boolean`	true if the action was performed

onPopulateEventForHost

Added in 1.0.0

protected void onPopulateEventForHost(@NonNull AccessibilityEvent event)

Populates an AccessibilityEvent with information about the host view.

The default implementation is a no-op.

Parameters
`@NonNull AccessibilityEvent event`	the event to populate with information about the host view

onPopulateEventForVirtualView

Added in 1.0.0

protected void onPopulateEventForVirtualView(
    int virtualViewId,
    @NonNull AccessibilityEvent event
)

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:

event text, see getText
content description, see setContentDescription
scrollability, see setScrollable
password state, see setPassword
enabled state, see setEnabled
checked state, see setChecked

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

item class name, set to the value used in onPopulateNodeForVirtualView
package name, set to the package of the host view's Context, see setPackageName
event source, set to the host view and virtual view identifier, see setSource

Parameters
`int virtualViewId`	The virtual view id for the item for which to populate the event
`@NonNull AccessibilityEvent event`	The event to populate

onPopulateNodeForHost

Added in 1.0.0

protected void onPopulateNodeForHost(@NonNull AccessibilityNodeInfoCompat node)

Populates an AccessibilityNodeInfoCompat with information about the host view.

The default implementation is a no-op.

Parameters
`@NonNull AccessibilityNodeInfoCompat node`	the node to populate with information about the host view

onPopulateNodeForVirtualView

Added in 1.0.0

protected abstract void onPopulateNodeForVirtualView(
    int virtualViewId,
    @NonNull AccessibilityNodeInfoCompat node
)

Populates an AccessibilityNodeInfoCompat with information about the specified item.

Implementations must populate the following required fields:

event text, see setText or setContentDescription
bounds in screen coordinates, see setBoundsInScreen and (AccessibilityNodeInfoCompat, Rect)

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

enabled state, set to true, see setEnabled
keyboard focusability, set to true, see setFocusable
item class name, set to android.view.View, see setClassName

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

package name, identical to the package name set by onPopulateEventForVirtualView, see setPackageName
node source, identical to the event source set in onPopulateEventForVirtualView, see setSource
parent view, set to the host view, see setParent
visibility, computed based on parent-relative bounds, see setVisibleToUser
accessibility focus, computed based on internal helper state, see setAccessibilityFocused
keyboard focus, computed based on internal helper state, see setFocused

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
`int virtualViewId`	The virtual view identifier of the item for which to populate the node
`@NonNull AccessibilityNodeInfoCompat node`	The node to populate

onVirtualViewKeyboardFocusChanged

Added in 1.0.0

protected void onVirtualViewKeyboardFocusChanged(int virtualViewId, boolean hasFocus)

Called when the focus state of a virtual view changes.

Parameters
`int virtualViewId`	the virtual view identifier
`boolean hasFocus`	`true` if the view has focus, `false` otherwise