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 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.
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 |
int
|
getFocusedVirtualView()
This method was deprecated
in API level 24.1.0.
Use |
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 |
void
|
onInitializeAccessibilityNodeInfo(View host, AccessibilityNodeInfoCompat info)
Initializes an |
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 |
void
|
onPopulateEventForVirtualView(int virtualViewId, AccessibilityEvent event)
Populates an |
void
|
onPopulateNodeForHost(AccessibilityNodeInfoCompat node)
Populates an |
abstract
void
|
onPopulateNodeForVirtualView(int virtualViewId, AccessibilityNodeInfoCompat node)
Populates an |
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
int HOST_ID
Virtual node identifier value for the host view's node.
Constant Value: -1 (0xffffffff)
INVALID_ID
int INVALID_ID
Virtual node identifier value for invalid nodes.
Constant Value: -2147483648 (0x80000000)
Public constructors
ExploreByTouchHelper
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
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
boolean dispatchHoverEvent (MotionEvent event)
Delegates hover events from the host view.
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
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
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
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
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.
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
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
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
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
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 |
See also:
invalidateVirtualView
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
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
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
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
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
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
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
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
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
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
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:
- event text, see
getText()
- content description, see
setContentDescription(CharSequence)
- scrollability, see
setScrollable(boolean)
- password state, see
setPassword(boolean)
- enabled state, see
setEnabled(boolean)
- checked state, see
setChecked(boolean)
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(int, AccessibilityNodeInfoCompat)
- package name, set to the package of the host view's
Context
, seesetPackageName(CharSequence)
- event source, set to the host view and virtual view identifier,
see
setSource(AccessibilityRecord, View, int)
Parameters | |
---|---|
virtualViewId |
int : The virtual view id for the item for which to
populate the event |
event |
AccessibilityEvent : The event to populate
|
onPopulateNodeForHost
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
void onPopulateNodeForVirtualView (int virtualViewId, AccessibilityNodeInfoCompat node)
Populates an AccessibilityNodeInfoCompat
with information
about the specified item.
Implementations must populate the following required fields:
- event text, see
setText(CharSequence)
orsetContentDescription(CharSequence)
- bounds in parent coordinates, see
setBoundsInParent(Rect)
The helper class automatically populates the following fields with default values, but implementations may optionally override them:
- enabled state, set to
true
, seesetEnabled(boolean)
- keyboard focusability, set to
true
, seesetFocusable(boolean)
- item class name, set to
android.view.View
, seesetClassName(CharSequence)
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(int, AccessibilityEvent)
, seesetPackageName(CharSequence)
- node source, identical to the event source set in
onPopulateEventForVirtualView(int, AccessibilityEvent)
, seesetSource(View, int)
- parent view, set to the host view, see
setParent(View)
- visibility, computed based on parent-relative bounds, see
setVisibleToUser(boolean)
- accessibility focus, computed based on internal helper state, see
setAccessibilityFocused(boolean)
- keyboard focus, computed based on internal helper state, see
setFocused(boolean)
- bounds in screen coordinates, computed based on host view bounds,
see
setBoundsInScreen(Rect)
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
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
|
Interfaces
Classes
- AutoScrollHelper
- CircularProgressDrawable
- CompoundButtonCompat
- ContentLoadingProgressBar
- CursorAdapter
- DrawerLayout
- DrawerLayout.LayoutParams
- DrawerLayout.SavedState
- DrawerLayout.SimpleDrawerListener
- EdgeEffectCompat
- ExploreByTouchHelper
- ImageViewCompat
- ListPopupWindowCompat
- ListViewAutoScrollHelper
- ListViewCompat
- NestedScrollView
- PopupMenuCompat
- PopupWindowCompat
- ResourceCursorAdapter
- ScrollerCompat
- SimpleCursorAdapter
- SlidingPaneLayout
- SlidingPaneLayout.LayoutParams
- SlidingPaneLayout.SimplePanelSlideListener
- Space
- SwipeRefreshLayout
- TextViewCompat
- ViewDragHelper
- ViewDragHelper.Callback