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  */
16 package 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
26 public 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      */
UiCollection(UiSelector selector)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      */
getChildByDescription(UiSelector childPattern, String text)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      */
getChildByInstance(UiSelector childPattern, int instance)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      */
getChildByText(UiSelector childPattern, String text)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      */
getChildCount(UiSelector childPattern)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