AccessibilityNodeProvider.java revision 021078554b902179442a345a9d080a165c3b5139
1021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov/* 2021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * Copyright (C) 2011 The Android Open Source Project 3021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 4021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * Licensed under the Apache License, Version 2.0 (the "License"); 5021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * you may not use this file except in compliance with the License. 6021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * You may obtain a copy of the License at 7021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 8021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * http://www.apache.org/licenses/LICENSE-2.0 9021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 10021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * Unless required by applicable law or agreed to in writing, software 11021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * distributed under the License is distributed on an "AS IS" BASIS, 12021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * See the License for the specific language governing permissions and 14021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * limitations under the License. 15021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov */ 16021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 17021078554b902179442a345a9d080a165c3b5139Svetoslav Ganovpackage android.view.accessibility; 18021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 19021078554b902179442a345a9d080a165c3b5139Svetoslav Ganovimport android.accessibilityservice.AccessibilityService; 20021078554b902179442a345a9d080a165c3b5139Svetoslav Ganovimport android.view.View; 21021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 22021078554b902179442a345a9d080a165c3b5139Svetoslav Ganovimport java.util.List; 23021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 24021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov/** 25021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * This class is the contract a client should implement to enable support of a 26021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * virtual view hierarchy rooted at a given view for accessibility purposes. A virtual 27021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * view hierarchy is a tree of imaginary Views that is reported as a part of the view 28021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * hierarchy when an {@link AccessibilityService} explores the window content. 29021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * Since the virtual View tree does not exist this class is responsible for 30021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * managing the {@link AccessibilityNodeInfo}s describing that tree to accessibility 31021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * services. 32021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * </p> 33021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <p> 34021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * The main use case of these APIs is to enable a custom view that draws complex content, 35021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * for example a monthly calendar grid, to be presented as a tree of logical nodes, 36021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * for example month days each containing events, thus conveying its logical structure. 37021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <p> 38021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <p> 39021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * A typical use case is to override {@link View#getAccessibilityNodeProvider()} of the 40021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * View that is a root of a virtual View hierarchy to return an instance of this class. 41021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * In such a case this instance is responsible for managing {@link AccessibilityNodeInfo}s 42021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * describing the virtual sub-tree rooted at the View including the one representing the 43021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * View itself. Similarly the returned instance is responsible for performing accessibility 44021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * actions on any virtual view or the root view itself. For example: 45021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * </p> 46021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <pre> 47021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * getAccessibilityNodeProvider( 48021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * if (mAccessibilityNodeProvider == null) { 49021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * mAccessibilityNodeProvider = new AccessibilityNodeProvider() { 50021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * public boolean performAccessibilityAction(int action, int virtualDescendantId) { 51021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * // Implementation. 52021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * return false; 53021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * } 54021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 55021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * public List<AccessibilityNodeInfo> findAccessibilityNodeInfosByText(String text, int virtualDescendantId) { 56021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * // Implementation. 57021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * return null; 58021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * } 59021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 60021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * public AccessibilityNodeInfo createAccessibilityNodeInfo(int virtualDescendantId) { 61021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * // Implementation. 62021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * return null; 63021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * } 64021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * }); 65021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * return mAccessibilityNodeProvider; 66021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * </pre> 67021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov */ 68021078554b902179442a345a9d080a165c3b5139Svetoslav Ganovpublic abstract class AccessibilityNodeProvider { 69021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 70021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov /** 71021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * Returns an {@link AccessibilityNodeInfo} representing a virtual view, 72021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * i.e. a descendant of the host View, with the given <code>virtualViewId</code> 73021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * or the host View itself if <code>virtualViewId</code> equals to {@link View#NO_ID}. 74021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <p> 75021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * A virtual descendant is an imaginary View that is reported as a part of the view 76021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * hierarchy for accessibility purposes. This enables custom views that draw complex 77021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * content to report them selves as a tree of virtual views, thus conveying their 78021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * logical structure. 79021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * </p> 80021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <p> 81021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * The implementer is responsible for obtaining an accessibility node info from the 82021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * pool of reusable instances and setting the desired properties of the node info 83021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * before returning it. 84021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * </p> 85021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 86021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @param virtualViewId A client defined virtual view id. 87021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @return A populated {@link AccessibilityNodeInfo} for a virtual descendant or the 88021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * host View. 89021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 90021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @see AccessibilityNodeInfo 91021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov */ 92021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov public AccessibilityNodeInfo createAccessibilityNodeInfo(int virtualViewId) { 93021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov return null; 94021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov } 95021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 96021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov /** 97021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * Performs an accessibility action on a virtual view, i.e. a descendant of the 98021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * host View, with the given <code>virtualViewId</code> or the host View itself 99021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * if <code>virtualViewId</code> equals to {@link View#NO_ID}. 100021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 101021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @param action The action to perform. 102021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @param virtualViewId A client defined virtual view id. 103021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @return True if the action was performed. 104021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 105021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @see #createAccessibilityNodeInfo(int) 106021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @see AccessibilityNodeInfo 107021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov */ 108021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov public boolean performAccessibilityAction(int action, int virtualViewId) { 109021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov return false; 110021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov } 111021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 112021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov /** 113021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * Finds {@link AccessibilityNodeInfo}s by text. The match is case insensitive 114021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * containment. The search is relative to the virtual view, i.e. a descendant of the 115021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * host View, with the given <code>virtualViewId</code> or the host View itself 116021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <code>virtualViewId</code> equals to {@link View#NO_ID}. 117021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 118021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @param virtualViewId A client defined virtual view id which defined 119021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * the root of the tree in which to perform the search. 120021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @param text The searched text. 121021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @return A list of node info. 122021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 123021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @see #createAccessibilityNodeInfo(int) 124021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @see AccessibilityNodeInfo 125021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov */ 126021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov public List<AccessibilityNodeInfo> findAccessibilityNodeInfosByText(String text, 127021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov int virtualViewId) { 128021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov return null; 129021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov } 130021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov} 131