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; 20aa780c110922148a6a4ba06734bb2b0bb8c98f93Svetoslav Ganovimport android.os.Bundle; 21021078554b902179442a345a9d080a165c3b5139Svetoslav Ganovimport android.view.View; 22021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 23021078554b902179442a345a9d080a165c3b5139Svetoslav Ganovimport java.util.List; 24021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 25021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov/** 26021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * This class is the contract a client should implement to enable support of a 27021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * virtual view hierarchy rooted at a given view for accessibility purposes. A virtual 28021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * view hierarchy is a tree of imaginary Views that is reported as a part of the view 29021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * hierarchy when an {@link AccessibilityService} explores the window content. 30021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * Since the virtual View tree does not exist this class is responsible for 31021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * managing the {@link AccessibilityNodeInfo}s describing that tree to accessibility 32021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * services. 33021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * </p> 34021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <p> 35021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * The main use case of these APIs is to enable a custom view that draws complex content, 36021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * for example a monthly calendar grid, to be presented as a tree of logical nodes, 37021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * for example month days each containing events, thus conveying its logical structure. 38021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <p> 39021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <p> 40021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * A typical use case is to override {@link View#getAccessibilityNodeProvider()} of the 41021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * View that is a root of a virtual View hierarchy to return an instance of this class. 42021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * In such a case this instance is responsible for managing {@link AccessibilityNodeInfo}s 43021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * describing the virtual sub-tree rooted at the View including the one representing the 44021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * View itself. Similarly the returned instance is responsible for performing accessibility 45021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * actions on any virtual view or the root view itself. For example: 46021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * </p> 47021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <pre> 48021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * getAccessibilityNodeProvider( 49021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * if (mAccessibilityNodeProvider == null) { 50021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * mAccessibilityNodeProvider = new AccessibilityNodeProvider() { 51aa780c110922148a6a4ba06734bb2b0bb8c98f93Svetoslav Ganov * public boolean performAction(int action, int virtualDescendantId) { 52021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * // Implementation. 53021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * return false; 54021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * } 55021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 56aa780c110922148a6a4ba06734bb2b0bb8c98f93Svetoslav Ganov * public List<AccessibilityNodeInfo> findAccessibilityNodeInfosByText(String text, 57aa780c110922148a6a4ba06734bb2b0bb8c98f93Svetoslav Ganov * int virtualDescendantId) { 58021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * // Implementation. 59021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * return null; 60021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * } 61021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 62021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * public AccessibilityNodeInfo createAccessibilityNodeInfo(int virtualDescendantId) { 63021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * // Implementation. 64021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * return null; 65021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * } 66021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * }); 67021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * return mAccessibilityNodeProvider; 68021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * </pre> 69021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov */ 70021078554b902179442a345a9d080a165c3b5139Svetoslav Ganovpublic abstract class AccessibilityNodeProvider { 71021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 72021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov /** 73021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * Returns an {@link AccessibilityNodeInfo} representing a virtual view, 74021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * i.e. a descendant of the host View, with the given <code>virtualViewId</code> 75021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * or the host View itself if <code>virtualViewId</code> equals to {@link View#NO_ID}. 76021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <p> 77021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * A virtual descendant is an imaginary View that is reported as a part of the view 78021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * hierarchy for accessibility purposes. This enables custom views that draw complex 79021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * content to report them selves as a tree of virtual views, thus conveying their 80021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * logical structure. 81021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * </p> 82021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <p> 83021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * The implementer is responsible for obtaining an accessibility node info from the 84021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * pool of reusable instances and setting the desired properties of the node info 85021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * before returning it. 86021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * </p> 87021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 88021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @param virtualViewId A client defined virtual view id. 89021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @return A populated {@link AccessibilityNodeInfo} for a virtual descendant or the 90021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * host View. 91021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 924213804541a8b05cd0587b138a2fd9a3b7fd9350Svetoslav Ganov * @see View#createAccessibilityNodeInfo() 93021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @see AccessibilityNodeInfo 94021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov */ 95021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov public AccessibilityNodeInfo createAccessibilityNodeInfo(int virtualViewId) { 96021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov return null; 97021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov } 98021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 99021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov /** 100021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * Performs an accessibility action on a virtual view, i.e. a descendant of the 101021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * host View, with the given <code>virtualViewId</code> or the host View itself 102021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * if <code>virtualViewId</code> equals to {@link View#NO_ID}. 103021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 104021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @param virtualViewId A client defined virtual view id. 105aa780c110922148a6a4ba06734bb2b0bb8c98f93Svetoslav Ganov * @param action The action to perform. 106aa780c110922148a6a4ba06734bb2b0bb8c98f93Svetoslav Ganov * @param arguments Optional action arguments. 107021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @return True if the action was performed. 108021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 109aa780c110922148a6a4ba06734bb2b0bb8c98f93Svetoslav Ganov * @see View#performAccessibilityAction(int, Bundle) 110021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @see #createAccessibilityNodeInfo(int) 111021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @see AccessibilityNodeInfo 112021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov */ 113aa780c110922148a6a4ba06734bb2b0bb8c98f93Svetoslav Ganov public boolean performAction(int virtualViewId, int action, Bundle arguments) { 114021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov return false; 115021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov } 116021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov 117021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov /** 118021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * Finds {@link AccessibilityNodeInfo}s by text. The match is case insensitive 119021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * containment. The search is relative to the virtual view, i.e. a descendant of the 120021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * host View, with the given <code>virtualViewId</code> or the host View itself 121021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * <code>virtualViewId</code> equals to {@link View#NO_ID}. 122021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 123021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @param virtualViewId A client defined virtual view id which defined 124021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * the root of the tree in which to perform the search. 125021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @param text The searched text. 126021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @return A list of node info. 127021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * 128021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @see #createAccessibilityNodeInfo(int) 129021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov * @see AccessibilityNodeInfo 130021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov */ 131021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov public List<AccessibilityNodeInfo> findAccessibilityNodeInfosByText(String text, 132021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov int virtualViewId) { 133021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov return null; 134021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov } 1352e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette 1362e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette /** 1372e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette * Find the virtual view, i.e. a descendant of the host View, that has the 1382e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette * specified focus type. 1392e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette * 1402e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette * @param focus The focus to find. One of 1412e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette * {@link AccessibilityNodeInfo#FOCUS_INPUT} or 1422e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette * {@link AccessibilityNodeInfo#FOCUS_ACCESSIBILITY}. 1432e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette * @return The node info of the focused view or null. 1442e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette * @see AccessibilityNodeInfo#FOCUS_INPUT 1452e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette * @see AccessibilityNodeInfo#FOCUS_ACCESSIBILITY 1462e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette */ 1472e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette public AccessibilityNodeInfo findFocus(int focus) { 1482e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette return null; 1492e1e081146546a04bc3813dde9c44babbddc0712Alan Viverette } 150021078554b902179442a345a9d080a165c3b5139Svetoslav Ganov} 151