android.support.v4.widget
Class ExploreByTouchHelper

java.lang.Object
  extended by android.support.v4.view.AccessibilityDelegateCompat
      extended by android.support.v4.widget.ExploreByTouchHelper

public abstract class ExploreByTouchHelper
extends 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. This class does not currently support hierarchies of logical items.

This should be applied to the parent view using ViewCompat.setAccessibilityDelegate(android.view.View, android.support.v4.view.AccessibilityDelegateCompat):

 mAccessHelper = ExploreByTouchHelper.create(someView, mAccessHelperCallback);
 ViewCompat.setAccessibilityDelegate(someView, mAccessHelper);
 


Field Summary
static int INVALID_ID
          Virtual node identifier value for invalid nodes.
 
Constructor Summary
ExploreByTouchHelper(android.view.View forView)
          Factory method to create a new ExploreByTouchHelper.
 
Method Summary
 boolean dispatchHoverEvent(android.view.MotionEvent event)
          Dispatches hover MotionEvents to the virtual view hierarchy when the Explore by Touch feature is enabled.
 AccessibilityNodeProviderCompat getAccessibilityNodeProvider(android.view.View host)
          Returns the AccessibilityNodeProviderCompat for this helper.
 int getFocusedVirtualView()
          Returns the virtual view id for the currently focused item,
protected abstract  int getVirtualViewAt(float x, float y)
          Provides a mapping between view-relative coordinates and logical items.
protected abstract  void getVisibleVirtualViews(java.util.List<java.lang.Integer> virtualViewIds)
          Populates a list with the view's visible items.
 void invalidateRoot()
          Notifies the accessibility framework that the properties of the parent view have changed.
 void invalidateVirtualView(int virtualViewId)
          Notifies the accessibility framework that the properties of a particular item have changed.
protected abstract  boolean onPerformActionForVirtualView(int virtualViewId, int action, android.os.Bundle arguments)
          Performs the specified accessibility action on the item associated with the virtual view identifier.
protected abstract  void onPopulateEventForVirtualView(int virtualViewId, android.view.accessibility.AccessibilityEvent event)
          Populates an AccessibilityEvent with information about the specified item.
protected abstract  void onPopulateNodeForVirtualView(int virtualViewId, AccessibilityNodeInfoCompat node)
          Populates an AccessibilityNodeInfoCompat with information about the specified item.
 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.
 
Methods inherited from class android.support.v4.view.AccessibilityDelegateCompat
dispatchPopulateAccessibilityEvent, onInitializeAccessibilityEvent, onInitializeAccessibilityNodeInfo, onPopulateAccessibilityEvent, onRequestSendAccessibilityEvent, performAccessibilityAction, sendAccessibilityEvent, sendAccessibilityEventUnchecked
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

INVALID_ID

public static final int INVALID_ID
Virtual node identifier value for invalid nodes.

See Also:
Constant Field Values
Constructor Detail

ExploreByTouchHelper

public ExploreByTouchHelper(android.view.View forView)
Factory method to create a new ExploreByTouchHelper.

Parameters:
forView - View whose logical children are exposed by this helper.
Method Detail

getAccessibilityNodeProvider

public AccessibilityNodeProviderCompat getAccessibilityNodeProvider(android.view.View host)
Returns the AccessibilityNodeProviderCompat for this helper.

Overrides:
getAccessibilityNodeProvider in class AccessibilityDelegateCompat
Parameters:
host - View whose logical children are exposed by this helper.
Returns:
The accessibility node provider for this helper.
See Also:
AccessibilityNodeProviderCompat

dispatchHoverEvent

public boolean dispatchHoverEvent(android.view.MotionEvent event)
Dispatches hover MotionEvents to the virtual view hierarchy when the Explore by Touch feature is enabled.

This method should be called by overriding View#dispatchHoverEvent:

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

Parameters:
event - The hover event to dispatch to the virtual view hierarchy.
Returns:
Whether the hover event was handled.

sendEventForVirtualView

public 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 - The virtual view id for which to send an event.
eventType - The type of event to send.
Returns:
true if the event was sent successfully.

invalidateRoot

public 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

public 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, android.support.v4.view.accessibility.AccessibilityNodeInfoCompat).

Parameters:
virtualViewId - The virtual view id to invalidate.

getFocusedVirtualView

public int getFocusedVirtualView()
Returns the virtual view id for the currently focused item,

Returns:
A virtual view id, or INVALID_ID if no item is currently focused.

getVirtualViewAt

protected abstract int getVirtualViewAt(float x,
                                        float y)
Provides a mapping between view-relative coordinates and logical items.

Parameters:
x - The view-relative x coordinate
y - The view-relative y coordinate
Returns:
virtual view identifier for the logical item under coordinates (x,y)

getVisibleVirtualViews

protected abstract void getVisibleVirtualViews(java.util.List<java.lang.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 - The list to populate with visible items

onPopulateEventForVirtualView

protected abstract void onPopulateEventForVirtualView(int virtualViewId,
                                                      android.view.accessibility.AccessibilityEvent event)
Populates an AccessibilityEvent 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:

Parameters:
virtualViewId - The virtual view id for the item for which to populate the event
event - The event to populate

onPopulateNodeForVirtualView

protected abstract 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 accessibility focus management by adding the appropriate AccessibilityNodeInfoCompat.ACTION_ACCESSIBILITY_FOCUS or AccessibilityNodeInfoCompat.ACTION_CLEAR_ACCESSIBILITY_FOCUS action. 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 - The virtual view identifier of the item for which to populate the node
node - The node to populate

onPerformActionForVirtualView

protected abstract boolean onPerformActionForVirtualView(int virtualViewId,
                                                         int action,
                                                         android.os.Bundle arguments)
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, android.support.v4.view.accessibility.AccessibilityNodeInfoCompat).

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

Parameters:
virtualViewId - The virtual view identifier of the item on which to perform the action
action - The accessibility action to perform
arguments - (Optional) A bundle with additional arguments, or null
Returns:
true if the action was performed