UiCollection.java revision e54d649fb83a0a44516e5c25a9ac1992c8950e59
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 verification 20 * and/or targeting a sub container by a child's text or description. For example 21 * if a list view contained many list items each in its own LinearLayout, and 22 * the test desired to locate an On/Off switch next to text Wi-Fi so not to be 23 * confused with a switch near text Bluetooth, the test use a UiCollection pointing 24 * at the list view of the items then use {@link #getChildByText(By, String)} for 25 * locating the LinearLayout element containing the text Wi-Fi. The returned UiObject 26 * can further be used to retrieve a child by selector targeting the desired switch and 27 * not other switches that may also be in the list. 28 */ 29public class UiCollection extends UiObject { 30 31 public UiCollection(By selector) { 32 super(selector); 33 } 34 35 /** 36 * Searches for child UI element within the constraints of this UiCollection {@link By} 37 * selector. It looks for any child matching the <code>childPattern</code> argument that has 38 * a child UI element anywhere within its sub hierarchy that has content-description text. 39 * The returned UiObject will point at the <code>childPattern</code> instance that matched the 40 * search and not at the identifying child element that matched the content description.</p> 41 * @param childPattern {@link By} selector of the child pattern to match and return 42 * @param text String of the identifying child contents of of the <code>childPattern</code> 43 * @return {@link UiObject} pointing at and instance of <code>childPattern</code> 44 * @throws UiObjectNotFoundException 45 */ 46 public UiObject getChildByDescription(By childPattern, String text) 47 throws UiObjectNotFoundException { 48 if (text != null) { 49 int count = getChildCount(childPattern); 50 for (int x = 0; x < count; x++) { 51 UiObject row = getChildByInstance(childPattern, x); 52 String nodeDesc = row.getContentDescription(); 53 if(nodeDesc != null && nodeDesc.contains(text)) { 54 return row; 55 } 56 UiObject item = row.getChild(By.selector().descriptionContains(text)); 57 if (item.exists()) { 58 return row; 59 } 60 } 61 } 62 throw new UiObjectNotFoundException("for description= \"" + text + "\""); 63 } 64 65 /** 66 * Searches for child UI element within the constraints of this UiCollection {@link By} 67 * selector. It looks for any child matching the <code>childPattern</code> argument that has 68 * a child UI element anywhere within its sub hierarchy that is at the <code>instance</code> 69 * specified. The operation is performed only on the visible items and no scrolling is performed 70 * in this case. 71 * @param childPattern {@link By} selector of the child pattern to match and return 72 * @param instance int the desired matched instance of this <code>childPattern</code> 73 * @return {@link UiObject} pointing at and instance of <code>childPattern</code> 74 */ 75 public UiObject getChildByInstance(By childPattern, int instance) 76 throws UiObjectNotFoundException { 77 By patternSelector = By.patternBuilder(getSelector(), 78 By.patternBuilder(childPattern).instance(instance)); 79 return new UiObject(patternSelector); 80 } 81 82 /** 83 * Searches for child UI element within the constraints of this UiCollection {@link By} 84 * selector. It looks for any child matching the <code>childPattern</code> argument that has 85 * a child UI element anywhere within its sub hierarchy that has text attribute = 86 * <code>text</code>. The returned UiObject will point at the <code>childPattern</code> 87 * instance that matched the search and not at the identifying child element that matched the 88 * text attribute.</p> 89 * @param childPattern {@link By} selector of the child pattern to match and return 90 * @param text String of the identifying child contents of of the <code>childPattern</code> 91 * @return {@link UiObject} pointing at and instance of <code>childPattern</code> 92 * @throws UiObjectNotFoundException 93 */ 94 public UiObject getChildByText(By childPattern, String text) 95 throws UiObjectNotFoundException { 96 97 if (text != null) { 98 int count = getChildCount(childPattern); 99 for (int x = 0; x < count; x++) { 100 UiObject row = getChildByInstance(childPattern, x); 101 String nodeText = row.getText(); 102 if(text.equals(nodeText)) { 103 return row; 104 } 105 UiObject item = row.getChild(By.selector().text(text)); 106 if (item.exists()) { 107 return row; 108 } 109 } 110 } 111 throw new UiObjectNotFoundException("for text= \"" + text + "\""); 112 } 113 114 /** 115 * Count child UI element instances matching the <code>childPattern</code> 116 * argument. The number of elements match returned represent those elements that are 117 * currently visible on the display within the sub hierarchy of this UiCollection {@link By} 118 * selector. Take note that more elements may be present but invisible and are not counted. 119 * @param childPattern is a {@link By} selector that is a pattern to count 120 * @return the number of matched childPattern under the current {@link UiCollection} 121 */ 122 public int getChildCount(By childPattern) { 123 By patternSelector = By.patternBuilder(getSelector(), By.patternBuilder(childPattern)); 124 return getQueryController().getPatternCount(patternSelector); 125 } 126} 127