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
17package com.google.android.droiddriver;
18
19import android.graphics.Rect;
20
21import com.google.android.droiddriver.actions.Action;
22import com.google.android.droiddriver.actions.ScrollDirection;
23import com.google.android.droiddriver.exceptions.ElementNotVisibleException;
24import com.google.android.droiddriver.finders.Attribute;
25import com.google.android.droiddriver.instrumentation.InstrumentationDriver;
26import com.google.android.droiddriver.uiautomation.UiAutomationDriver;
27import com.google.common.base.Predicate;
28
29import 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 */
38public 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