1/*
2 * Copyright (C) 2012 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 */
16package com.android.uiautomator.core;
17
18/**
19 * Used to enumerate a container's UI elements for the purpose of counting,
20 * or targeting a sub elements by a child's text or description.
21 * @since API Level 16
22 * @deprecated New tests should be written using UI Automator 2.0 which is available as part of the
23 * Android Testing Support Library.
24 */
25@Deprecated
26public class UiCollection extends UiObject {
27
28    /**
29     * Constructs an instance as described by the selector
30     *
31     * @param selector
32     * @since API Level 16
33     */
34    public UiCollection(UiSelector selector) {
35        super(selector);
36    }
37
38    /**
39     * Searches for child UI element within the constraints of this UiCollection {@link UiSelector}
40     * selector.
41     *
42     * It looks for any child matching the <code>childPattern</code> argument that has
43     * a child UI element anywhere within its sub hierarchy that has content-description text.
44     * The returned UiObject will point at the <code>childPattern</code> instance that matched the
45     * search and not at the identifying child element that matched the content description.</p>
46     *
47     * @param childPattern {@link UiSelector} selector of the child pattern to match and return
48     * @param text String of the identifying child contents of of the <code>childPattern</code>
49     * @return {@link UiObject} pointing at and instance of <code>childPattern</code>
50     * @throws UiObjectNotFoundException
51     * @since API Level 16
52     */
53    public UiObject getChildByDescription(UiSelector childPattern, String text)
54            throws UiObjectNotFoundException {
55        Tracer.trace(childPattern, text);
56        if (text != null) {
57            int count = getChildCount(childPattern);
58            for (int x = 0; x < count; x++) {
59                UiObject row = getChildByInstance(childPattern, x);
60                String nodeDesc = row.getContentDescription();
61                if(nodeDesc != null && nodeDesc.contains(text)) {
62                    return row;
63                }
64                UiObject item = row.getChild(new UiSelector().descriptionContains(text));
65                if (item.exists()) {
66                    return row;
67                }
68            }
69        }
70        throw new UiObjectNotFoundException("for description= \"" + text + "\"");
71    }
72
73    /**
74     * Searches for child UI element within the constraints of this UiCollection {@link UiSelector}
75     * selector.
76     *
77     * It looks for any child matching the <code>childPattern</code> argument that has
78     * a child UI element anywhere within its sub hierarchy that is at the <code>instance</code>
79     * specified. The operation is performed only on the visible items and no scrolling is performed
80     * in this case.
81     *
82     * @param childPattern {@link UiSelector} selector of the child pattern to match and return
83     * @param instance int the desired matched instance of this <code>childPattern</code>
84     * @return {@link UiObject} pointing at and instance of <code>childPattern</code>
85     * @since API Level 16
86     */
87    public UiObject getChildByInstance(UiSelector childPattern, int instance)
88            throws UiObjectNotFoundException {
89        Tracer.trace(childPattern, instance);
90        UiSelector patternSelector = UiSelector.patternBuilder(getSelector(),
91                UiSelector.patternBuilder(childPattern).instance(instance));
92        return new UiObject(patternSelector);
93    }
94
95    /**
96     * Searches for child UI element within the constraints of this UiCollection {@link UiSelector}
97     * selector.
98     *
99     * It looks for any child matching the <code>childPattern</code> argument that has
100     * a child UI element anywhere within its sub hierarchy that has text attribute =
101     * <code>text</code>. The returned UiObject will point at the <code>childPattern</code>
102     * instance that matched the search and not at the identifying child element that matched the
103     * text attribute.</p>
104     *
105     * @param childPattern {@link UiSelector} selector of the child pattern to match and return
106     * @param text String of the identifying child contents of of the <code>childPattern</code>
107     * @return {@link UiObject} pointing at and instance of <code>childPattern</code>
108     * @throws UiObjectNotFoundException
109     * @since API Level 16
110     */
111    public UiObject getChildByText(UiSelector childPattern, String text)
112            throws UiObjectNotFoundException {
113        Tracer.trace(childPattern, text);
114        if (text != null) {
115            int count = getChildCount(childPattern);
116            for (int x = 0; x < count; x++) {
117                UiObject row = getChildByInstance(childPattern, x);
118                String nodeText = row.getText();
119                if(text.equals(nodeText)) {
120                    return row;
121                }
122                UiObject item = row.getChild(new UiSelector().text(text));
123                if (item.exists()) {
124                    return row;
125                }
126            }
127        }
128        throw new UiObjectNotFoundException("for text= \"" + text + "\"");
129    }
130
131    /**
132     * Counts child UI element instances matching the <code>childPattern</code>
133     * argument. The method returns the number of matching UI elements that are
134     * currently visible.  The count does not include items of a scrollable list
135     * that are off-screen.
136     *
137     * @param childPattern a {@link UiSelector} that represents the matching child UI
138     * elements to count
139     * @return the number of matched childPattern under the current {@link UiCollection}
140     * @since API Level 16
141     */
142    public int getChildCount(UiSelector childPattern) {
143        Tracer.trace(childPattern);
144        UiSelector patternSelector =
145                UiSelector.patternBuilder(getSelector(), UiSelector.patternBuilder(childPattern));
146        return getQueryController().getPatternCount(patternSelector);
147    }
148}
149