1 /* 2 * Copyright (C) 2013 DroidDriver committers 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 17 package com.google.android.droiddriver; 18 19 import android.graphics.Rect; 20 21 import com.google.android.droiddriver.actions.Action; 22 import com.google.android.droiddriver.actions.ScrollDirection; 23 import com.google.android.droiddriver.exceptions.ElementNotVisibleException; 24 import com.google.android.droiddriver.finders.Attribute; 25 import com.google.android.droiddriver.instrumentation.InstrumentationDriver; 26 import com.google.android.droiddriver.uiautomation.UiAutomationDriver; 27 import com.google.common.base.Predicate; 28 29 import java.util.List; 30 31 /** 32 * Represents an UI element within an Android App. 33 * <p> 34 * UI elements are generally views. Users can get attributes and perform 35 * actions. Note that actions often update UiElement, so users are advised not 36 * to store instances for later use -- the instances could become stale. 37 */ 38 public interface UiElement { 39 /** 40 * Gets the text of this element. 41 */ 42 String getText(); 43 44 /** 45 * Gets the content description of this element. 46 */ 47 String getContentDescription(); 48 49 /** 50 * Gets the class name of the underlying view. The actual name could be 51 * overridden. 52 * 53 * @see com.google.android.droiddriver.instrumentation.ViewElement#overrideClassName 54 */ 55 String getClassName(); 56 57 /** 58 * Gets the resource id of this element. 59 */ 60 String getResourceId(); 61 62 /** 63 * Gets the package name of this element. 64 */ 65 String getPackageName(); 66 67 /** 68 * @return whether or not this element is visible on the device's display. 69 */ 70 boolean isVisible(); 71 72 /** 73 * @return whether this element is checkable. 74 */ 75 boolean isCheckable(); 76 77 /** 78 * @return whether this element is checked. 79 */ 80 boolean isChecked(); 81 82 /** 83 * @return whether this element is clickable. 84 */ 85 boolean isClickable(); 86 87 /** 88 * @return whether this element is enabled. 89 */ 90 boolean isEnabled(); 91 92 /** 93 * @return whether this element is focusable. 94 */ 95 boolean isFocusable(); 96 97 /** 98 * @return whether this element is focused. 99 */ 100 boolean isFocused(); 101 102 /** 103 * @return whether this element is scrollable. 104 */ 105 boolean isScrollable(); 106 107 /** 108 * @return whether this element is long-clickable. 109 */ 110 boolean isLongClickable(); 111 112 /** 113 * @return whether this element is password. 114 */ 115 boolean isPassword(); 116 117 /** 118 * @return whether this element is selected. 119 */ 120 boolean isSelected(); 121 122 /** 123 * Gets the UiElement bounds in screen coordinates. The coordinates may not be 124 * visible on screen. 125 */ 126 Rect getBounds(); 127 128 /** 129 * Gets the UiElement bounds in screen coordinates. The coordinates will be 130 * visible on screen. 131 */ 132 Rect getVisibleBounds(); 133 134 /** 135 * @return value of the given attribute. 136 */ 137 <T> T get(Attribute attribute); 138 139 /** 140 * Executes the given action. 141 * 142 * @param action The action to execute 143 * @throws ElementNotVisibleException when the element is not visible 144 * @return true if the action is successful 145 */ 146 boolean perform(Action action); 147 148 /** 149 * Sets the text of this element. 150 * 151 * @param text The text to enter. 152 * @throws ElementNotVisibleException when the element is not visible 153 */ 154 // TODO: Should this clear the text before setting? 155 void setText(String text); 156 157 /** 158 * Clicks this element. The click will be at the center of the visible 159 * element. 160 * 161 * @throws ElementNotVisibleException when the element is not visible 162 */ 163 void click(); 164 165 /** 166 * Long-clicks this element. The click will be at the center of the visible 167 * element. 168 * 169 * @throws ElementNotVisibleException when the element is not visible 170 */ 171 void longClick(); 172 173 /** 174 * Double-clicks this element. The click will be at the center of the visible 175 * element. 176 * 177 * @throws ElementNotVisibleException when the element is not visible 178 */ 179 void doubleClick(); 180 181 /** 182 * Scrolls in the given direction. Scrolling down means swiping upwards. 183 */ 184 void scroll(ScrollDirection direction); 185 186 /** 187 * Gets an immutable {@link List} of immediate children that satisfy 188 * {@code predicate}. It always filters children that are null. 189 */ 190 List<UiElement> getChildren(Predicate<? super UiElement> predicate); 191 192 /** 193 * Filters out invisible children. 194 */ 195 Predicate<UiElement> VISIBLE = new Predicate<UiElement>() { 196 @Override 197 public boolean apply(UiElement element) { 198 return element.isVisible(); 199 } 200 201 @Override 202 public String toString() { 203 return "VISIBLE"; 204 } 205 }; 206 207 // TODO: remove getChildCount and getChild. 208 /** 209 * Gets the child at given index. 210 */ 211 UiElement getChild(int index); 212 213 /** 214 * Gets the child count. This gives a low level access to the underlying data. 215 * Do not use it unless you are sure about the subtle details. Note the count 216 * may not be what you expect. For instance, a dynamic list may show more 217 * items when scrolling beyond the end, varying the count. The count also 218 * depends on the driver implementation: 219 * <ul> 220 * <li>{@link InstrumentationDriver} includes all.</li> 221 * <li>the Accessibility API (which {@link UiAutomationDriver} depends on) 222 * does not include off-screen children, but may include invisible on-screen 223 * children.</li> 224 * </ul> 225 */ 226 int getChildCount(); 227 228 /** 229 * Gets the parent. 230 */ 231 UiElement getParent(); 232 } 233
