added in version 22.1.0
belongs to Maven artifact com.android.support:customview:28.0.0-alpha1

ExploreByTouchHelper

public abstract class ExploreByTouchHelper
extends AccessibilityDelegateCompat

java.lang.Object
   ↳ android.support.v4.view.AccessibilityDelegateCompat
     ↳ android.support.v4.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(View, AccessibilityDelegateCompat):

 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

int HOST_ID

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

int INVALID_ID

Virtual node identifier value for invalid nodes.

Public constructors

ExploreByTouchHelper(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(MotionEvent event)

Delegates hover events from the host view.

final boolean dispatchKeyEvent(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 AccessibilityServices that explore the window content.

int getFocusedVirtualView()

This method was deprecated in API level 24.1.0. 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, 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.

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, Bundle arguments)

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

void onPopulateEventForHost(AccessibilityEvent event)

Populates an AccessibilityEvent with information about the host view.

void onPopulateEventForVirtualView(int virtualViewId, AccessibilityEvent event)

Populates an AccessibilityEvent with information about the specified item.

void onPopulateNodeForHost(AccessibilityNodeInfoCompat node)

Populates an AccessibilityNodeInfoCompat with information about the host view.

abstract void onPopulateNodeForVirtualView(int virtualViewId, 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 class android.support.v4.view.AccessibilityDelegateCompat
From class java.lang.Object

Constants

HOST_ID

added in version 24.1.0
int HOST_ID

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

Constant Value: -1 (0xffffffff)

INVALID_ID

added in version 22.1.0
int INVALID_ID

Virtual node identifier value for invalid nodes.

Constant Value: -2147483648 (0x80000000)

Public constructors

ExploreByTouchHelper

added in version 22.1.0
ExploreByTouchHelper (View host)

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

added in version 24.1.0
boolean clearKeyboardFocusForVirtualView (int virtualViewId)

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 version 22.1.0
boolean dispatchHoverEvent (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(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.

Returns
boolean Whether the hover event was handled.

dispatchKeyEvent

added in version 24.1.0
boolean dispatchKeyEvent (KeyEvent event)

Delegates key events from the host view.

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

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

Parameters
event KeyEvent

Returns
boolean

getAccessibilityFocusedVirtualViewId

added in version 24.1.0
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

added in version 22.1.0
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.

Parameters
host View

Returns
AccessibilityNodeProviderCompat The provider.

getFocusedVirtualView

added in version 22.1.0
int getFocusedVirtualView ()

This method was deprecated in API level 24.1.0.
Use getAccessibilityFocusedVirtualViewId().

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

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

invalidateVirtualView

added in version 24.1.0
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(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

added in version 24.1.0
void onFocusChanged (boolean gainFocus, 
                int direction, 
                Rect previouslyFocusedRect)

Delegates focus changes from the host view.

This method should be called by overriding the host view's 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);
 }
 

Parameters
gainFocus boolean

direction int

previouslyFocusedRect Rect

onInitializeAccessibilityEvent

added in version 22.1.0
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
host View: The View hosting the delegate.

event AccessibilityEvent: The event to initialize.

onInitializeAccessibilityNodeInfo

added in version 22.1.0
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
host View: The View hosting the delegate.

info AccessibilityNodeInfoCompat: The instance to initialize.

requestKeyboardFocusForVirtualView

added in version 24.1.0
boolean requestKeyboardFocusForVirtualView (int virtualViewId)

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 version 22.1.0
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
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

Protected methods

getVirtualViewAt

added in version 22.1.0
int getVirtualViewAt (float x, 
                float y)

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 version 22.1.0
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
virtualViewIds List: The list to populate with visible items

onPerformActionForVirtualView

added in version 22.1.0
boolean onPerformActionForVirtualView (int virtualViewId, 
                int action, 
                Bundle arguments)

Performs the specified accessibility action on the item associated with the virtual view identifier. See 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 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 version 24.1.0
void onPopulateEventForHost (AccessibilityEvent event)

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 version 22.1.0
void onPopulateEventForVirtualView (int virtualViewId, 
                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(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 AccessibilityEvent: The event to populate

onPopulateNodeForHost

added in version 24.1.0
void onPopulateNodeForHost (AccessibilityNodeInfoCompat node)

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 version 22.1.0
void onPopulateNodeForVirtualView (int virtualViewId, 
                AccessibilityNodeInfoCompat node)

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 version 24.1.0
void onVirtualViewKeyboardFocusChanged (int virtualViewId, 
                boolean hasFocus)

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