UiElement.java revision f9c2a591497874769b87bf492a0666cf853e0ae5 
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.ElementNotFoundException;
24import com.google.android.droiddriver.exceptions.ElementNotVisibleException;
25import com.google.android.droiddriver.matchers.Matcher;
26
27/**
28 * Represents an UI element within an Android App.
29 *
30 * <p>
31 * UI elements are generally views.
32 */
33public interface UiElement {
34  /**
35   * Finds the first {@link UiElement} that matches the given matcher,
36   * traversing from this element. If the elements tree may change, use
37   * {@link DroidDriver#waitForElement(Matcher)}.
38   *
39   * @param matcher The matching mechanism
40   * @return The first matching element on the current context
41   * @throws ElementNotFoundException If no matching elements are found
42   */
43  UiElement findElement(Matcher matcher);
44
45  /**
46   * @return Whether a matching element exists
47   */
48  boolean hasElement(Matcher matcher);
49
50  /**
51   * Gets the text of this element.
52   */
53  String getText();
54
55  /**
56   * Gets the content description of this element.
57   */
58  String getContentDescription();
59
60  /**
61   * Gets the class name of the underlying view.
62   */
63  String getClassName();
64
65  /**
66   * Gets the resource id of this element.
67   */
68  String getResourceId();
69
70  /**
71   * Gets the package name of this element.
72   */
73  String getPackageName();
74
75  /**
76   * @return whether or not this element is visible on the device's display.
77   */
78  boolean isVisible();
79
80  /**
81   * @return whether this element is checkable.
82   */
83  boolean isCheckable();
84
85  /**
86   * @return whether this element is checked.
87   */
88  boolean isChecked();
89
90  /**
91   * @return whether this element is clickable.
92   */
93  boolean isClickable();
94
95  /**
96   * @return whether this element is enabled.
97   */
98  boolean isEnabled();
99
100  /**
101   * @return whether this element is focusable.
102   */
103  boolean isFocusable();
104
105  /**
106   * @return whether this element is focused.
107   */
108  boolean isFocused();
109
110  /**
111   * @return whether this element is scrollable.
112   */
113  boolean isScrollable();
114
115  /**
116   * @return whether this element is long-clickable.
117   */
118  boolean isLongClickable();
119
120  /**
121   * @return whether this element is password.
122   */
123  boolean isPassword();
124
125  /**
126   * @return whether this element is selected.
127   */
128  boolean isSelected();
129
130  /**
131   * Gets the UiElement bounds in screen coordinates. The coordinates may not be
132   * visible on screen.
133   */
134  Rect getRect();
135
136  /**
137   * Executes the given action.
138   *
139   * @param action The action to execute
140   * @return true if the action is successful
141   */
142  boolean perform(Action action);
143
144  /**
145   * Sets the text of this element.
146   *
147   * @param text The text to enter.
148   * @throws ElementNotVisibleException when the element is not visible
149   */
150  // TODO: Should this clear the text before setting?
151  void setText(String text);
152
153  /**
154   * Clicks this element. The click will be at the center of the visible
155   * element.
156   *
157   * @throws ElementNotVisibleException when the element is not visible
158   */
159  void click();
160
161  /**
162   * Long-clicks this element. The click will be at the center of the visible
163   * element.
164   *
165   * @throws ElementNotVisibleException when the element is not visible
166   */
167  void longClick();
168
169  /**
170   * Double-clicks this element. The click will be at the center of the visible
171   * element.
172   *
173   * @throws ElementNotVisibleException when the element is not visible
174   */
175  void doubleClick();
176
177  /**
178   * Scrolls in the given direction. Scrolling down means swiping upwards.
179   */
180  void scroll(ScrollDirection direction);
181}
182