UiCollection.java revision 3d50587be8ff021369c90554d814839335b445b0
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(UiSelector, 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(UiSelector selector) { 32 super(selector); 33 } 34 35 /** 36 * Searches for child UI element within the constraints of this UiCollection {@link UiSelector} 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 * 42 * @param childPattern {@link UiSelector} selector of the child pattern to match and return 43 * @param text String of the identifying child contents of of the <code>childPattern</code> 44 * @return {@link UiObject} pointing at and instance of <code>childPattern</code> 45 * @throws UiObjectNotFoundException 46 */ 47 public UiObject getChildByDescription(UiSelector childPattern, String text) 48 throws UiObjectNotFoundException { 49 if (text != null) { 50 int count = getChildCount(childPattern); 51 for (int x = 0; x < count; x++) { 52 UiObject row = getChildByInstance(childPattern, x); 53 String nodeDesc = row.getContentDescription(); 54 if(nodeDesc != null && nodeDesc.contains(text)) { 55 return row; 56 } 57 UiObject item = row.getChild(new UiSelector().descriptionContains(text)); 58 if (item.exists()) { 59 return row; 60 } 61 } 62 } 63 throw new UiObjectNotFoundException("for description= \"" + text + "\""); 64 } 65 66 /** 67 * Searches for child UI element within the constraints of this UiCollection {@link UiSelector} 68 * selector. It looks for any child matching the <code>childPattern</code> argument that has 69 * a child UI element anywhere within its sub hierarchy that is at the <code>instance</code> 70 * specified. The operation is performed only on the visible items and no scrolling is performed 71 * in this case. 72 * 73 * @param childPattern {@link UiSelector} selector of the child pattern to match and return 74 * @param instance int the desired matched instance of this <code>childPattern</code> 75 * @return {@link UiObject} pointing at and instance of <code>childPattern</code> 76 */ 77 public UiObject getChildByInstance(UiSelector childPattern, int instance) 78 throws UiObjectNotFoundException { 79 UiSelector patternSelector = UiSelector.patternBuilder(getSelector(), 80 UiSelector.patternBuilder(childPattern).instance(instance)); 81 return new UiObject(patternSelector); 82 } 83 84 /** 85 * Searches for child UI element within the constraints of this UiCollection {@link UiSelector} 86 * selector. It looks for any child matching the <code>childPattern</code> argument that has 87 * a child UI element anywhere within its sub hierarchy that has text attribute = 88 * <code>text</code>. The returned UiObject will point at the <code>childPattern</code> 89 * instance that matched the search and not at the identifying child element that matched the 90 * text attribute.</p> 91 * 92 * @param childPattern {@link UiSelector} selector of the child pattern to match and return 93 * @param text String of the identifying child contents of of the <code>childPattern</code> 94 * @return {@link UiObject} pointing at and instance of <code>childPattern</code> 95 * @throws UiObjectNotFoundException 96 */ 97 public UiObject getChildByText(UiSelector childPattern, String text) 98 throws UiObjectNotFoundException { 99 100 if (text != null) { 101 int count = getChildCount(childPattern); 102 for (int x = 0; x < count; x++) { 103 UiObject row = getChildByInstance(childPattern, x); 104 String nodeText = row.getText(); 105 if(text.equals(nodeText)) { 106 return row; 107 } 108 UiObject item = row.getChild(new UiSelector().text(text)); 109 if (item.exists()) { 110 return row; 111 } 112 } 113 } 114 throw new UiObjectNotFoundException("for text= \"" + text + "\""); 115 } 116 117 /** 118 * Count child UI element instances matching the <code>childPattern</code> 119 * argument. The number of elements match returned represent those elements that are 120 * currently visible on the display within the sub hierarchy of this UiCollection 121 * {@link UiSelector} selector. Take note that more elements may be present but 122 * invisible and are not counted. 123 * 124 * @param childPattern is a {@link UiSelector} selector that is a pattern to count 125 * @return the number of matched childPattern under the current {@link UiCollection} 126 */ 127 public int getChildCount(UiSelector childPattern) { 128 UiSelector patternSelector = 129 UiSelector.patternBuilder(getSelector(), UiSelector.patternBuilder(childPattern)); 130 return getQueryController().getPatternCount(patternSelector); 131 } 132} 133