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 io.appium.droiddriver; 18 19 import android.graphics.Rect; 20 21 import java.util.List; 22 23 import io.appium.droiddriver.actions.Action; 24 import io.appium.droiddriver.actions.InputInjector; 25 import io.appium.droiddriver.finders.Attribute; 26 import io.appium.droiddriver.finders.Predicate; 27 import io.appium.droiddriver.instrumentation.InstrumentationDriver; 28 import io.appium.droiddriver.scroll.Direction.PhysicalDirection; 29 import io.appium.droiddriver.uiautomation.UiAutomationDriver; 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 */ getText()42 String getText(); 43 44 /** 45 * Gets the content description of this element. 46 */ getContentDescription()47 String getContentDescription(); 48 49 /** 50 * Gets the class name of the underlying view. The actual name could be 51 * overridden. 52 * 53 * @see io.appium.droiddriver.instrumentation.ViewElement#overrideClassName 54 */ getClassName()55 String getClassName(); 56 57 /** 58 * Gets the resource id of this element. 59 */ getResourceId()60 String getResourceId(); 61 62 /** 63 * Gets the package name of this element. 64 */ getPackageName()65 String getPackageName(); 66 67 /** 68 * @return whether or not this element is visible on the device's display. 69 */ isVisible()70 boolean isVisible(); 71 72 /** 73 * @return whether this element is checkable. 74 */ isCheckable()75 boolean isCheckable(); 76 77 /** 78 * @return whether this element is checked. 79 */ isChecked()80 boolean isChecked(); 81 82 /** 83 * @return whether this element is clickable. 84 */ isClickable()85 boolean isClickable(); 86 87 /** 88 * @return whether this element is enabled. 89 */ isEnabled()90 boolean isEnabled(); 91 92 /** 93 * @return whether this element is focusable. 94 */ isFocusable()95 boolean isFocusable(); 96 97 /** 98 * @return whether this element is focused. 99 */ isFocused()100 boolean isFocused(); 101 102 /** 103 * @return whether this element is scrollable. 104 */ isScrollable()105 boolean isScrollable(); 106 107 /** 108 * @return whether this element is long-clickable. 109 */ isLongClickable()110 boolean isLongClickable(); 111 112 /** 113 * @return whether this element is password. 114 */ isPassword()115 boolean isPassword(); 116 117 /** 118 * @return whether this element is selected. 119 */ isSelected()120 boolean isSelected(); 121 122 /** 123 * Gets the UiElement bounds in screen coordinates. The coordinates may not be 124 * visible on screen. 125 */ getBounds()126 Rect getBounds(); 127 128 /** 129 * Gets the UiElement bounds in screen coordinates. The coordinates will be 130 * visible on screen. 131 */ getVisibleBounds()132 Rect getVisibleBounds(); 133 134 /** 135 * @return value of the given attribute. 136 */ get(Attribute attribute)137 <T> T get(Attribute attribute); 138 139 /** 140 * Executes the given action. 141 * 142 * @param action the action to execute 143 * @return true if the action is successful 144 */ perform(Action action)145 boolean perform(Action action); 146 147 /** 148 * Sets the text of this element. The implementation may not work on all UiElements if the 149 * underlying view is not EditText. <p> If this element already has text, it is cleared first if 150 * the device has API 11 or higher. <p> TODO: Support this behavior on older devices. <p> The IME 151 * (soft keyboard) may be shown after this call. If the {@code text} ends with {@code '\n'}, the 152 * IME may be closed automatically. If the IME is open, you can call {@link UiDevice#pressBack()} 153 * to close it. <p> If you are using {@link io.appium.droiddriver.instrumentation.InstrumentationDriver}, 154 * you may use {@link io.appium.droiddriver.actions.view.CloseKeyboardAction} to close it. The 155 * advantage of {@code CloseKeyboardAction} is that it is a no-op if the IME is hidden. This is 156 * useful when the state of the IME cannot be determined. 157 * 158 * @param text the text to enter 159 */ setText(String text)160 void setText(String text); 161 162 /** 163 * Clicks this element. The click will be at the center of the visible 164 * element. 165 */ click()166 void click(); 167 168 /** 169 * Long-clicks this element. The click will be at the center of the visible 170 * element. 171 */ longClick()172 void longClick(); 173 174 /** 175 * Double-clicks this element. The click will be at the center of the visible 176 * element. 177 */ doubleClick()178 void doubleClick(); 179 180 /** 181 * Scrolls in the given direction. 182 * 183 * @param direction specifies where the view port will move instead of the finger 184 */ scroll(PhysicalDirection direction)185 void scroll(PhysicalDirection direction); 186 187 /** 188 * Gets an immutable {@link List} of immediate children that satisfy 189 * {@code predicate}. It always filters children that are null. This gives a 190 * low level access to the underlying data. Do not use it unless you are sure 191 * about the subtle details. Note the count may not be what you expect. For 192 * instance, a dynamic list may show more items when scrolling beyond the end, 193 * varying the count. The count also depends on the driver implementation: 194 * <ul> 195 * <li>{@link InstrumentationDriver} includes all.</li> 196 * <li>the Accessibility API (which {@link UiAutomationDriver} depends on) 197 * does not include off-screen children, but may include invisible on-screen 198 * children.</li> 199 * </ul> 200 * <p> 201 * Another discrepancy between {@link InstrumentationDriver} 202 * {@link UiAutomationDriver} is the order of children. The Accessibility API 203 * returns children in the order of layout (see 204 * {@link android.view.ViewGroup#addChildrenForAccessibility}, which is added 205 * in API16). 206 * </p> 207 */ getChildren(Predicate<? super UiElement> predicate)208 List<? extends UiElement> getChildren(Predicate<? super UiElement> predicate); 209 210 /** 211 * Filters out invisible children. 212 */ 213 Predicate<UiElement> VISIBLE = new Predicate<UiElement>() { 214 @Override 215 public boolean apply(UiElement element) { 216 return element.isVisible(); 217 } 218 219 @Override 220 public String toString() { 221 return "VISIBLE"; 222 } 223 }; 224 225 /** 226 * Gets the parent. 227 */ getParent()228 UiElement getParent(); 229 230 /** 231 * Gets the {@link InputInjector} for injecting InputEvent. 232 */ getInjector()233 InputInjector getInjector(); 234 } 235