page.title=UiSelector parent.title=uiautomator parent.link=index.html @jd:body

Class Overview

This class provides the mechanism for tests to describe the UI elements they intend to target. A UI element has many properties associated with it such as text value, content-description, class name and multiple state information like selected, enabled, checked etc. Additionally UiSelector allows targeting of UI elements within a specific display hierarchies to distinguish similar elements based in the hierarchies they're in.

Summary

Public Constructors
UiSelector()
Public Methods
UiSelector checked(boolean val)
Set the search criteria to match widgets that are currently checked (usually for checkboxes).
UiSelector childSelector(UiSelector selector)
Adds a child UiSelector criteria to this selector.
UiSelector className(String className)
Set the search criteria to match the class property for a widget (for example, "android.widget.Button").
<T> UiSelector className(Class<T> type)
Set the search criteria to match the class property for a widget (for example, "android.widget.Button").
UiSelector classNameMatches(String regex)
Set the search criteria to match the class property for a widget (for example, "android.widget.Button").
UiSelector clickable(boolean val)
Set the search criteria to match widgets that are clickable.
UiSelector description(String desc)
Set the search criteria to match the content-description property for a widget.
UiSelector descriptionContains(String desc)
Set the search criteria to match the content-description property for a widget.
UiSelector descriptionMatches(String regex)
Set the search criteria to match the content-description property for a widget.
UiSelector descriptionStartsWith(String desc)
Set the search criteria to match the content-description property for a widget.
UiSelector enabled(boolean val)
Set the search criteria to match widgets that are enabled.
UiSelector focusable(boolean val)
Set the search criteria to match widgets that are focusable.
UiSelector focused(boolean val)
Set the search criteria to match widgets that have focus.
UiSelector fromParent(UiSelector selector)
Adds a child UiSelector criteria to this selector which is used to start search from the parent widget.
UiSelector index(int index)
Set the search criteria to match the widget by its node index in the layout hierarchy.
UiSelector instance(int instance)
Set the search criteria to match the widget by its instance number.
UiSelector longClickable(boolean val)
Set the search criteria to match widgets that are long-clickable.
UiSelector packageName(String name)
Set the search criteria to match the package name of the application that contains the widget.
UiSelector packageNameMatches(String regex)
Set the search criteria to match the package name of the application that contains the widget.
UiSelector scrollable(boolean val)
Set the search criteria to match widgets that are scrollable.
UiSelector selected(boolean val)
Set the search criteria to match widgets that are currently selected.
UiSelector text(String text)
Set the search criteria to match the visible text displayed for a widget (for example, the text label to launch an app).
UiSelector textContains(String text)
Set the search criteria to match the visible text displayed for a widget (for example, the text label to launch an app).
UiSelector textMatches(String regex)
Set the search criteria to match the visible text displayed for a widget (for example, the text label to launch an app).
UiSelector textStartsWith(String text)
Text property is usually the widget's visible text on the display.
String toString()
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public UiSelector ()

Public Methods

public UiSelector checked (boolean val)

Set the search criteria to match widgets that are currently checked (usually for checkboxes). Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
val Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector childSelector (UiSelector selector)

Adds a child UiSelector criteria to this selector. Use this selector to narrow the search scope to child widgets under a specific parent widget.

Returns
  • UiSelector with this added search criterion

public UiSelector className (String className)

Set the search criteria to match the class property for a widget (for example, "android.widget.Button").

Parameters
className Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector className (Class<T> type)

Set the search criteria to match the class property for a widget (for example, "android.widget.Button").

Returns
  • UiSelector with the specified search criteria
Since
  • Android API Level 17

public UiSelector classNameMatches (String regex)

Set the search criteria to match the class property for a widget (for example, "android.widget.Button").

Returns
  • UiSelector with the specified search criteria
Since
  • Android API Level 17

public UiSelector clickable (boolean val)

Set the search criteria to match widgets that are clickable. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
val Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector description (String desc)

Set the search criteria to match the content-description property for a widget. The content-description is typically used by the Android Accessibility framework to provide an audio prompt for the widget when the widget is selected. The content-description for the widget must match exactly with the string in your input argument. Matching is case-sensitive.

Parameters
desc Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector descriptionContains (String desc)

Set the search criteria to match the content-description property for a widget. The content-description is typically used by the Android Accessibility framework to provide an audio prompt for the widget when the widget is selected. The content-description for the widget must contain the string in your input argument. Matching is case-insensitive.

Parameters
desc Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector descriptionMatches (String regex)

Set the search criteria to match the content-description property for a widget. The content-description is typically used by the Android Accessibility framework to provide an audio prompt for the widget when the widget is selected. The content-description for the widget must match exactly with the string in your input argument.

Returns
  • UiSelector with the specified search criteria
Since
  • Android API Level 17

public UiSelector descriptionStartsWith (String desc)

Set the search criteria to match the content-description property for a widget. The content-description is typically used by the Android Accessibility framework to provide an audio prompt for the widget when the widget is selected. The content-description for the widget must start with the string in your input argument. Matching is case-insensitive.

Parameters
desc Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector enabled (boolean val)

Set the search criteria to match widgets that are enabled. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
val Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector focusable (boolean val)

Set the search criteria to match widgets that are focusable. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
val Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector focused (boolean val)

Set the search criteria to match widgets that have focus. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
val Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector fromParent (UiSelector selector)

Adds a child UiSelector criteria to this selector which is used to start search from the parent widget. Use this selector to narrow the search scope to sibling widgets as well all child widgets under a parent.

Returns
  • UiSelector with this added search criterion

public UiSelector index (int index)

Set the search criteria to match the widget by its node index in the layout hierarchy. The index value must be 0 or greater. Using the index can be unreliable and should only be used as a last resort for matching. Instead, consider using the instance(int) method.

Parameters
index Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector instance (int instance)

Set the search criteria to match the widget by its instance number. The instance value must be 0 or greater, where the first instance is 0. For example, to simulate a user click on the third image that is enabled in a UI screen, you could specify a a search criteria where the instance is 2, the className(String) matches the image widget class, and enabled(boolean) is true. The code would look like this: new UiSelector().className("android.widget.ImageView") .enabled(true).instance(2);

Parameters
instance Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector longClickable (boolean val)

Set the search criteria to match widgets that are long-clickable. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
val Value to match
Returns
  • UiSelector with the specified search criteria
Since
  • Android API Level 17

public UiSelector packageName (String name)

Set the search criteria to match the package name of the application that contains the widget.

Parameters
name Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector packageNameMatches (String regex)

Set the search criteria to match the package name of the application that contains the widget.

Returns
  • UiSelector with the specified search criteria
Since
  • Android API Level 17

public UiSelector scrollable (boolean val)

Set the search criteria to match widgets that are scrollable. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
val Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector selected (boolean val)

Set the search criteria to match widgets that are currently selected. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
val Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector text (String text)

Set the search criteria to match the visible text displayed for a widget (for example, the text label to launch an app). The text for the widget must match exactly with the string in your input argument. Matching is case-sensitive.

Parameters
text Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector textContains (String text)

Set the search criteria to match the visible text displayed for a widget (for example, the text label to launch an app). The text for the widget must contain the string in your input argument. Matching is case-sensitive.

Parameters
text Value to match
Returns
  • UiSelector with the specified search criteria

public UiSelector textMatches (String regex)

Set the search criteria to match the visible text displayed for a widget (for example, the text label to launch an app). The text for the widget must match exactly with the string in your input argument.

Returns
  • UiSelector with the specified search criteria
Since
  • Android API Level 17

public UiSelector textStartsWith (String text)

Text property is usually the widget's visible text on the display. Adding this to the search criteria indicates that the search performed should match a widget with text value starting with the text parameter. The matching will be case-insensitive.

Returns
  • UiSelector with this added search criterion

public String toString ()