1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.view.accessibility;
18
19import android.accessibilityservice.AccessibilityService;
20import android.os.Bundle;
21import android.view.View;
22
23import java.util.List;
24
25/**
26 * This class is the contract a client should implement to enable support of a
27 * virtual view hierarchy rooted at a given view for accessibility purposes. A virtual
28 * view hierarchy is a tree of imaginary Views that is reported as a part of the view
29 * hierarchy when an {@link AccessibilityService} explores the window content.
30 * Since the virtual View tree does not exist this class is responsible for
31 * managing the {@link AccessibilityNodeInfo}s describing that tree to accessibility
32 * services.
33 * </p>
34 * <p>
35 * The main use case of these APIs is to enable a custom view that draws complex content,
36 * for example a monthly calendar grid, to be presented as a tree of logical nodes,
37 * for example month days each containing events, thus conveying its logical structure.
38 * <p>
39 * <p>
40 * A typical use case is to override {@link View#getAccessibilityNodeProvider()} of the
41 * View that is a root of a virtual View hierarchy to return an instance of this class.
42 * In such a case this instance is responsible for managing {@link AccessibilityNodeInfo}s
43 * describing the virtual sub-tree rooted at the View including the one representing the
44 * View itself. Similarly the returned instance is responsible for performing accessibility
45 * actions on any virtual view or the root view itself. For example:
46 * </p>
47 * <pre>
48 *     getAccessibilityNodeProvider(
49 *         if (mAccessibilityNodeProvider == null) {
50 *             mAccessibilityNodeProvider = new AccessibilityNodeProvider() {
51 *                 public boolean performAction(int action, int virtualDescendantId) {
52 *                     // Implementation.
53 *                     return false;
54 *                 }
55 *
56 *                 public List<AccessibilityNodeInfo> findAccessibilityNodeInfosByText(String text,
57 *                         int virtualDescendantId) {
58 *                     // Implementation.
59 *                     return null;
60 *                 }
61 *
62 *                 public AccessibilityNodeInfo createAccessibilityNodeInfo(int virtualDescendantId) {
63 *                     // Implementation.
64 *                     return null;
65 *                 }
66 *             });
67 *     return mAccessibilityNodeProvider;
68 * </pre>
69 */
70public abstract class AccessibilityNodeProvider {
71
72    /**
73     * Returns an {@link AccessibilityNodeInfo} representing a virtual view,
74     * i.e. a descendant of the host View, with the given <code>virtualViewId</code>
75     * or the host View itself if <code>virtualViewId</code> equals to {@link View#NO_ID}.
76     * <p>
77     * A virtual descendant is an imaginary View that is reported as a part of the view
78     * hierarchy for accessibility purposes. This enables custom views that draw complex
79     * content to report them selves as a tree of virtual views, thus conveying their
80     * logical structure.
81     * </p>
82     * <p>
83     * The implementer is responsible for obtaining an accessibility node info from the
84     * pool of reusable instances and setting the desired properties of the node info
85     * before returning it.
86     * </p>
87     *
88     * @param virtualViewId A client defined virtual view id.
89     * @return A populated {@link AccessibilityNodeInfo} for a virtual descendant or the
90     *     host View.
91     *
92     * @see View#createAccessibilityNodeInfo()
93     * @see AccessibilityNodeInfo
94     */
95    public AccessibilityNodeInfo createAccessibilityNodeInfo(int virtualViewId) {
96        return null;
97    }
98
99    /**
100     * Performs an accessibility action on a virtual view, i.e. a descendant of the
101     * host View, with the given <code>virtualViewId</code> or the host View itself
102     * if <code>virtualViewId</code> equals to {@link View#NO_ID}.
103     *
104     * @param virtualViewId A client defined virtual view id.
105     * @param action The action to perform.
106     * @param arguments Optional action arguments.
107     * @return True if the action was performed.
108     *
109     * @see View#performAccessibilityAction(int, Bundle)
110     * @see #createAccessibilityNodeInfo(int)
111     * @see AccessibilityNodeInfo
112     */
113    public boolean performAction(int virtualViewId, int action, Bundle arguments) {
114        return false;
115    }
116
117    /**
118     * Finds {@link AccessibilityNodeInfo}s by text. The match is case insensitive
119     * containment. The search is relative to the virtual view, i.e. a descendant of the
120     * host View, with the given <code>virtualViewId</code> or the host View itself
121     * <code>virtualViewId</code> equals to {@link View#NO_ID}.
122     *
123     * @param virtualViewId A client defined virtual view id which defined
124     *     the root of the tree in which to perform the search.
125     * @param text The searched text.
126     * @return A list of node info.
127     *
128     * @see #createAccessibilityNodeInfo(int)
129     * @see AccessibilityNodeInfo
130     */
131    public List<AccessibilityNodeInfo> findAccessibilityNodeInfosByText(String text,
132            int virtualViewId) {
133        return null;
134    }
135}
136