public abstract class ExploreByTouchHelper extends AccessibilityDelegateCompat
View
s 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.
Clients should override abstract methods on this class and attach it to the
host view using ViewCompat.setAccessibilityDelegate(android.view.View, android.support.v4.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);
Modifier and Type | Field and Description |
---|---|
static int |
HOST_ID
Virtual node identifier value for the host view's node.
|
static int |
INVALID_ID
Virtual node identifier value for invalid nodes.
|
Constructor and Description |
---|
ExploreByTouchHelper(View host)
Constructs a new helper that can expose a virtual view hierarchy for the
specified host view.
|
Modifier and Type | Method and Description |
---|---|
boolean |
clearKeyboardFocusForVirtualView(int virtualViewId)
Attempts to clear keyboard focus from a virtual view.
|
boolean |
dispatchHoverEvent(MotionEvent event)
Delegates hover events from the host view.
|
boolean |
dispatchKeyEvent(KeyEvent event)
Delegates key events from the host view.
|
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()
Deprecated.
|
int |
getKeyboardFocusedVirtualViewId() |
protected abstract int |
getVirtualViewAt(float x,
float y)
Provides a mapping between view-relative coordinates and logical
items.
|
protected abstract void |
getVisibleVirtualViews(List<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.
|
void |
invalidateVirtualView(int virtualViewId,
int changeTypes)
Notifies the accessibility framework that the properties of a particular
item have changed.
|
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. |
protected abstract boolean |
onPerformActionForVirtualView(int virtualViewId,
int action,
Bundle arguments)
Performs the specified accessibility action on the item associated
with the virtual view identifier.
|
protected void |
onPopulateEventForHost(AccessibilityEvent event)
Populates an
AccessibilityEvent with information about the host
view. |
protected void |
onPopulateEventForVirtualView(int virtualViewId,
AccessibilityEvent event)
Populates an
AccessibilityEvent with information about the
specified item. |
protected void |
onPopulateNodeForHost(AccessibilityNodeInfoCompat node)
Populates an
AccessibilityNodeInfoCompat with information
about the host view. |
protected abstract void |
onPopulateNodeForVirtualView(int virtualViewId,
AccessibilityNodeInfoCompat node)
Populates an
AccessibilityNodeInfoCompat with information
about the specified item. |
protected void |
onVirtualViewKeyboardFocusChanged(int virtualViewId,
boolean hasFocus)
Called when the focus state of a virtual view changes.
|
boolean |
requestKeyboardFocusForVirtualView(int virtualViewId)
Attempts to give keyboard focus to a virtual view.
|
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.
|
dispatchPopulateAccessibilityEvent, onPopulateAccessibilityEvent, onRequestSendAccessibilityEvent, performAccessibilityAction, sendAccessibilityEvent, sendAccessibilityEventUnchecked
public static final int INVALID_ID
public static final int HOST_ID
public ExploreByTouchHelper(View host)
host
- view whose virtual view hierarchy is exposed by this helperpublic AccessibilityNodeProviderCompat getAccessibilityNodeProvider(View host)
AccessibilityDelegateCompat
AccessibilityService
s
that explore the window content.
The default implementation behaves as
ViewCompat#getAccessibilityNodeProvider(View)
for the case of no accessibility delegate been set.
getAccessibilityNodeProvider
in class AccessibilityDelegateCompat
AccessibilityNodeProviderCompat
public final boolean dispatchHoverEvent(@NonNull MotionEvent event)
Dispatches hover MotionEvent
s 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); }
event
- The hover event to dispatch to the virtual view hierarchy.public final boolean dispatchKeyEvent(@NonNull KeyEvent event)
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); }
public final void onFocusChanged(boolean gainFocus, int direction, @Nullable Rect previouslyFocusedRect)
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); }
public final int getAccessibilityFocusedVirtualViewId()
INVALID_ID
if no virtual view has accessibility
focuspublic final int getKeyboardFocusedVirtualViewId()
INVALID_ID
if no virtual view has keyboard focuspublic final boolean sendEventForVirtualView(int virtualViewId, int eventType)
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); }
virtualViewId
- the identifier of the virtual view for which to
send an eventeventType
- the type of event to sendtrue
if the event was sent successfully, false
otherwisepublic final void invalidateRoot()
You must call this method after adding or removing items from the parent view.
public final void invalidateVirtualView(int virtualViewId)
You must call this method after changing any of the
properties set in
onPopulateNodeForVirtualView(int, AccessibilityNodeInfoCompat)
.
virtualViewId
- the virtual view id to invalidate, or
HOST_ID
to invalidate the root viewinvalidateVirtualView(int, int)
public final void invalidateVirtualView(int virtualViewId, int changeTypes)
You must call this method after changing any of the
properties set in
onPopulateNodeForVirtualView(int, AccessibilityNodeInfoCompat)
.
virtualViewId
- the virtual view id to invalidate, or
HOST_ID
to invalidate the root viewchangeTypes
- the bit mask of change types. May be 0
for the
default (undefined) change type or one or more of:
@Deprecated public int getFocusedVirtualView()
getAccessibilityFocusedVirtualViewId()
.INVALID_ID
if no virtual view has accessibility
focusprotected void onVirtualViewKeyboardFocusChanged(int virtualViewId, boolean hasFocus)
virtualViewId
- the virtual view identifierhasFocus
- true
if the view has focus, false
otherwisepublic void onInitializeAccessibilityEvent(View host, AccessibilityEvent event)
AccessibilityDelegateCompat
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.
onInitializeAccessibilityEvent
in class AccessibilityDelegateCompat
host
- The View hosting the delegate.event
- The event to initialize.ViewCompat#onInitializeAccessibilityEvent(View, AccessibilityEvent)
public void onInitializeAccessibilityNodeInfo(View host, AccessibilityNodeInfoCompat info)
AccessibilityDelegateCompat
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.
onInitializeAccessibilityNodeInfo
in class AccessibilityDelegateCompat
host
- The View hosting the delegate.info
- The instance to initialize.ViewCompat#onInitializeAccessibilityNodeInfo(View, AccessibilityNodeInfoCompat)
public final boolean requestKeyboardFocusForVirtualView(int virtualViewId)
virtualViewId
- the identifier of the virtual view on which to
place keyboard focuspublic final boolean clearKeyboardFocusForVirtualView(int virtualViewId)
virtualViewId
- the identifier of the virtual view from which to
clear keyboard focusprotected abstract int getVirtualViewAt(float x, float y)
x
- The view-relative x coordinatey
- The view-relative y coordinateHOST_ID
if there is no item at
the given coordinatesprotected abstract void getVisibleVirtualViews(List<Integer> virtualViewIds)
virtualViewIds
specifies order of accessibility focus
traversal.virtualViewIds
- The list to populate with visible itemsprotected void onPopulateEventForVirtualView(int virtualViewId, AccessibilityEvent event)
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:
AccessibilityRecord.getText()
AccessibilityRecord.setContentDescription(CharSequence)
AccessibilityRecord.setScrollable(boolean)
AccessibilityRecord.setPassword(boolean)
AccessibilityRecord.setEnabled(boolean)
AccessibilityRecord.setChecked(boolean)
The following required fields are automatically populated by the helper class and may not be overridden:
onPopulateNodeForVirtualView(int, AccessibilityNodeInfoCompat)
Context
, see AccessibilityEvent.setPackageName(java.lang.CharSequence)
AccessibilityRecordCompat.setSource(View, int)
virtualViewId
- The virtual view id for the item for which to
populate the eventevent
- The event to populateprotected void onPopulateEventForHost(AccessibilityEvent event)
AccessibilityEvent
with information about the host
view.
The default implementation is a no-op.
event
- the event to populate with information about the host viewprotected abstract void onPopulateNodeForVirtualView(int virtualViewId, AccessibilityNodeInfoCompat node)
AccessibilityNodeInfoCompat
with information
about the specified item.
Implementations must populate the following required fields:
AccessibilityNodeInfoCompat.setText(CharSequence)
or
AccessibilityNodeInfoCompat.setContentDescription(CharSequence)
AccessibilityNodeInfoCompat.setBoundsInParent(Rect)
The helper class automatically populates the following fields with default values, but implementations may optionally override them:
true
, see
AccessibilityNodeInfoCompat.setEnabled(boolean)
true
, see
AccessibilityNodeInfoCompat.setFocusable(boolean)
android.view.View
, see
AccessibilityNodeInfoCompat.setClassName(CharSequence)
The following required fields are automatically populated by the helper class and may not be overridden:
onPopulateEventForVirtualView(int, AccessibilityEvent)
, see
AccessibilityNodeInfoCompat.setPackageName(java.lang.CharSequence)
onPopulateEventForVirtualView(int, AccessibilityEvent)
, see
AccessibilityNodeInfoCompat.setSource(View, int)
AccessibilityNodeInfoCompat.setParent(View)
AccessibilityNodeInfoCompat.setVisibleToUser(boolean)
AccessibilityNodeInfoCompat.setAccessibilityFocused(boolean)
AccessibilityNodeInfoCompat.setFocused(boolean)
AccessibilityNodeInfoCompat.setBoundsInScreen(Rect)
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.
virtualViewId
- The virtual view identifier of the item for
which to populate the nodenode
- The node to populateprotected void onPopulateNodeForHost(AccessibilityNodeInfoCompat node)
AccessibilityNodeInfoCompat
with information
about the host view.
The default implementation is a no-op.
node
- the node to populate with information about the host viewprotected abstract boolean onPerformActionForVirtualView(int virtualViewId, int action, Bundle arguments)
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.
virtualViewId
- The virtual view identifier of the item on which
to perform the actionaction
- The accessibility action to performarguments
- (Optional) A bundle with additional arguments, or
null