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.InputInjector;
23import com.google.android.droiddriver.finders.Attribute;
24import com.google.android.droiddriver.finders.Predicate;
25import com.google.android.droiddriver.instrumentation.InstrumentationDriver;
26import com.google.android.droiddriver.scroll.Direction.PhysicalDirection;
27import com.google.android.droiddriver.uiautomation.UiAutomationDriver;
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   * @return true if the action is successful
144   */
145  boolean perform(Action action);
146
147  /**
148   * Sets the text of this element.
149   *
150   * @param text The text to enter.
151   */
152  void setText(String text);
153
154  /**
155   * Clicks this element. The click will be at the center of the visible
156   * element.
157   */
158  void click();
159
160  /**
161   * Long-clicks this element. The click will be at the center of the visible
162   * element.
163   */
164  void longClick();
165
166  /**
167   * Double-clicks this element. The click will be at the center of the visible
168   * element.
169   */
170  void doubleClick();
171
172  /**
173   * Scrolls in the given direction.
174   *
175   * @param direction specifies where the view port will move, instead of the
176   *        finger.
177   */
178  void scroll(PhysicalDirection direction);
179
180  /**
181   * Gets an immutable {@link List} of immediate children that satisfy
182   * {@code predicate}. It always filters children that are null. This gives a
183   * low level access to the underlying data. Do not use it unless you are sure
184   * about the subtle details. Note the count may not be what you expect. For
185   * instance, a dynamic list may show more items when scrolling beyond the end,
186   * varying the count. The count also depends on the driver implementation:
187   * <ul>
188   * <li>{@link InstrumentationDriver} includes all.</li>
189   * <li>the Accessibility API (which {@link UiAutomationDriver} depends on)
190   * does not include off-screen children, but may include invisible on-screen
191   * children.</li>
192   * </ul>
193   * <p>
194   * Another discrepancy between {@link InstrumentationDriver}
195   * {@link UiAutomationDriver} is the order of children. The Accessibility API
196   * returns children in the order of layout (see
197   * {@link android.view.ViewGroup#addChildrenForAccessibility}, which is added
198   * in API16).
199   * </p>
200   */
201  List<? extends UiElement> getChildren(Predicate<? super UiElement> predicate);
202
203  /**
204   * Filters out invisible children.
205   */
206  Predicate<UiElement> VISIBLE = new Predicate<UiElement>() {
207    @Override
208    public boolean apply(UiElement element) {
209      return element.isVisible();
210    }
211
212    @Override
213    public String toString() {
214      return "VISIBLE";
215    }
216  };
217
218  /**
219   * Gets the parent.
220   */
221  UiElement getParent();
222
223  /**
224   * Gets the {@link InputInjector} for injecting InputEvent.
225   */
226  InputInjector getInjector();
227}
228