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     * The virtual id for the hosting View.
74     */
75    public static final int HOST_VIEW_ID = -1;
76
77    /**
78     * Returns an {@link AccessibilityNodeInfo} representing a virtual view,
79     * i.e. a descendant of the host View, with the given <code>virtualViewId</code>
80     * or the host View itself if <code>virtualViewId</code> equals to {@link #HOST_VIEW_ID}.
81     * <p>
82     * A virtual descendant is an imaginary View that is reported as a part of the view
83     * hierarchy for accessibility purposes. This enables custom views that draw complex
84     * content to report them selves as a tree of virtual views, thus conveying their
85     * logical structure.
86     * </p>
87     * <p>
88     * The implementer is responsible for obtaining an accessibility node info from the
89     * pool of reusable instances and setting the desired properties of the node info
90     * before returning it.
91     * </p>
92     *
93     * @param virtualViewId A client defined virtual view id.
94     * @return A populated {@link AccessibilityNodeInfo} for a virtual descendant or the
95     *     host View.
96     *
97     * @see View#createAccessibilityNodeInfo()
98     * @see AccessibilityNodeInfo
99     */
100    public AccessibilityNodeInfo createAccessibilityNodeInfo(int virtualViewId) {
101        return null;
102    }
103
104    /**
105     * Performs an accessibility action on a virtual view, i.e. a descendant of the
106     * host View, with the given <code>virtualViewId</code> or the host View itself
107     * if <code>virtualViewId</code> equals to {@link #HOST_VIEW_ID}.
108     *
109     * @param virtualViewId A client defined virtual view id.
110     * @param action The action to perform.
111     * @param arguments Optional action arguments.
112     * @return True if the action was performed.
113     *
114     * @see View#performAccessibilityAction(int, Bundle)
115     * @see #createAccessibilityNodeInfo(int)
116     * @see AccessibilityNodeInfo
117     */
118    public boolean performAction(int virtualViewId, int action, Bundle arguments) {
119        return false;
120    }
121
122    /**
123     * Finds {@link AccessibilityNodeInfo}s by text. The match is case insensitive
124     * containment. The search is relative to the virtual view, i.e. a descendant of the
125     * host View, with the given <code>virtualViewId</code> or the host View itself
126     * <code>virtualViewId</code> equals to {@link #HOST_VIEW_ID}.
127     *
128     * @param virtualViewId A client defined virtual view id which defined
129     *     the root of the tree in which to perform the search.
130     * @param text The searched text.
131     * @return A list of node info.
132     *
133     * @see #createAccessibilityNodeInfo(int)
134     * @see AccessibilityNodeInfo
135     */
136    public List<AccessibilityNodeInfo> findAccessibilityNodeInfosByText(String text,
137            int virtualViewId) {
138        return null;
139    }
140
141    /**
142     * Find the virtual view, i.e. a descendant of the host View, that has the
143     * specified focus type.
144     *
145     * @param focus The focus to find. One of
146     *            {@link AccessibilityNodeInfo#FOCUS_INPUT} or
147     *            {@link AccessibilityNodeInfo#FOCUS_ACCESSIBILITY}.
148     * @return The node info of the focused view or null.
149     * @see AccessibilityNodeInfo#FOCUS_INPUT
150     * @see AccessibilityNodeInfo#FOCUS_ACCESSIBILITY
151     */
152    public AccessibilityNodeInfo findFocus(int focus) {
153        return null;
154    }
155}
156