Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)

UiScrollable

A UiCollection that supports searching for items in scrollable layout elements. This class can be used with horizontally or vertically scrollable controls.

Summary

[Expand]
Inherited Constants
From class com.android.uiautomator.core.UiObject
Public Constructors
UiScrollable ( UiSelector container)
Constructor.
Public Methods
boolean flingBackward ()
Performs a backwards fling action with the default number of fling steps (5).
boolean flingForward ()
Performs a forward fling with the default number of fling steps (5).
boolean flingToBeginning (int maxSwipes)
Performs a fling gesture to reach the beginning of a scrollable layout element.
boolean flingToEnd (int maxSwipes)
Performs a fling gesture to reach the end of a scrollable layout element.
UiObject getChildByDescription ( UiSelector childPattern, String text, boolean allowScrollSearch)
Searches for a child element in the present scrollable container.
UiObject getChildByDescription ( UiSelector childPattern, String text)
Searches for a child element in the present scrollable container.
UiObject getChildByInstance ( UiSelector childPattern, int instance)
Searches for a child element in the present scrollable container that matches the selector you provided.
UiObject getChildByText ( UiSelector childPattern, String text, boolean allowScrollSearch)
Searches for a child element in the present scrollable container.
UiObject getChildByText ( UiSelector childPattern, String text)
Searches for a child element in the present scrollable container.
int getMaxSearchSwipes ()
Gets the maximum number of scrolls allowed when performing a scroll action in search of a child element.
double getSwipeDeadZonePercentage ()
Returns the percentage of a widget's size that's considered as a no-touch zone when swiping.
boolean scrollBackward (int steps)
Performs a backward scroll.
boolean scrollBackward ()
Performs a backward scroll with the default number of scroll steps (55).
boolean scrollDescriptionIntoView (String text)
Performs a forward scroll action on the scrollable layout element until the content-description is found, or until swipe attempts have been exhausted.
boolean scrollForward ()
Performs a forward scroll with the default number of scroll steps (55).
boolean scrollForward (int steps)
Performs a forward scroll.
boolean scrollIntoView ( UiSelector selector)
Perform a scroll forward action to move through the scrollable layout element until a visible item that matches the selector is found.
boolean scrollIntoView ( UiObject obj)
Perform a forward scroll action to move through the scrollable layout element until a visible item that matches the UiObject is found.
boolean scrollTextIntoView (String text)
Performs a forward scroll action on the scrollable layout element until the text you provided is visible, or until swipe attempts have been exhausted.
boolean scrollToBeginning (int maxSwipes)
Scrolls to the beginning of a scrollable layout element.
boolean scrollToBeginning (int maxSwipes, int steps)
Scrolls to the beginning of a scrollable layout element.
boolean scrollToEnd (int maxSwipes, int steps)
Scrolls to the end of a scrollable layout element.
boolean scrollToEnd (int maxSwipes)
Scrolls to the end of a scrollable layout element.
UiScrollable setAsHorizontalList ()
Set the direction of swipes to be horizontal when performing scroll actions.
UiScrollable setAsVerticalList ()
Set the direction of swipes to be vertical when performing scroll actions.
UiScrollable setMaxSearchSwipes (int swipes)
Sets the maximum number of scrolls allowed when performing a scroll action in search of a child element.
UiScrollable setSwipeDeadZonePercentage (double swipeDeadZonePercentage)
Sets the percentage of a widget's size that's considered as no-touch zone when swiping.
Protected Methods
boolean exists ( UiSelector selector)
Used privately when performing swipe searches to decide if an element has become visible or not.
[Expand]
Inherited Methods
From class com.android.uiautomator.core.UiCollection
From class com.android.uiautomator.core.UiObject
From class java.lang.Object

Public Constructors

public UiScrollable ( UiSelector container)

Constructor.

Parameters
container a UiSelector selector to identify the scrollable layout element.

Public Methods

public boolean flingBackward ()

Performs a backwards fling action with the default number of fling steps (5). If the swipe direction is set to vertical, then the swipe will be performed from top to bottom. If the swipe direction is set to horizontal, then the swipes will be performed from left to right. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
  • true if scrolled, and false if can't scroll anymore
Throws
UiObjectNotFoundException

public boolean flingForward ()

Performs a forward fling with the default number of fling steps (5). If the swipe direction is set to vertical, then the swipes will be performed from bottom to top. If the swipe direction is set to horizontal, then the swipes will be performed from right to left. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
  • true if scrolled, false if can't scroll anymore
Throws
UiObjectNotFoundException

public boolean flingToBeginning (int maxSwipes)

Performs a fling gesture to reach the beginning of a scrollable layout element. The beginning can be at the top-most edge in the case of vertical controls, or the left-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
  • true on scrolled else false
Throws
UiObjectNotFoundException

public boolean flingToEnd (int maxSwipes)

Performs a fling gesture to reach the end of a scrollable layout element. The end can be at the bottom-most edge in the case of vertical controls, or the right-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
  • true on scrolled, else false
Throws
UiObjectNotFoundException

public UiObject getChildByDescription ( UiSelector childPattern, String text, boolean allowScrollSearch)

Searches for a child element in the present scrollable container. The search first looks for a child element that matches the selector you provided, then looks for the content-description in its children elements. If both search conditions are fulfilled, the method returns a {@ link UiObject} representing the element matching the selector (not the child element in its subhierarchy containing the content-description).

Parameters
childPattern UiSelector for a child in a scollable layout element
text Content-description to find in the children of the childPattern match (may be a partial match)
allowScrollSearch set to true if scrolling is allowed
Returns
  • UiObject representing the child element that matches the search conditions
Throws
UiObjectNotFoundException

public UiObject getChildByDescription ( UiSelector childPattern, String text)

Searches for a child element in the present scrollable container. The search first looks for a child element that matches the selector you provided, then looks for the content-description in its children elements. If both search conditions are fulfilled, the method returns a {@ link UiObject} representing the element matching the selector (not the child element in its subhierarchy containing the content-description). By default, this method performs a scroll search. See getChildByDescription(UiSelector, String, boolean)

Parameters
childPattern UiSelector for a child in a scollable layout element
text Content-description to find in the children of the childPattern match
Returns
  • UiObject representing the child element that matches the search conditions
Throws
UiObjectNotFoundException

public UiObject getChildByInstance ( UiSelector childPattern, int instance)

Searches for a child element in the present scrollable container that matches the selector you provided. The search is performed without scrolling and only on visible elements.

Parameters
childPattern UiSelector for a child in a scollable layout element
instance int number representing the occurance of a childPattern match
Returns
  • UiObject representing the child element that matches the search conditions
Throws
UiObjectNotFoundException

public UiObject getChildByText ( UiSelector childPattern, String text, boolean allowScrollSearch)

Searches for a child element in the present scrollable container. The search first looks for a child element that matches the selector you provided, then looks for the text in its children elements. If both search conditions are fulfilled, the method returns a {@ link UiObject} representing the element matching the selector (not the child element in its subhierarchy containing the text).

Parameters
childPattern UiSelector selector for a child in a scrollable layout element
text String to find in the children of the childPattern match
allowScrollSearch set to true if scrolling is allowed
Returns
  • UiObject representing the child element that matches the search conditions
Throws
UiObjectNotFoundException

public UiObject getChildByText ( UiSelector childPattern, String text)

Searches for a child element in the present scrollable container. The search first looks for a child element that matches the selector you provided, then looks for the text in its children elements. If both search conditions are fulfilled, the method returns a {@ link UiObject} representing the element matching the selector (not the child element in its subhierarchy containing the text). By default, this method performs a scroll search. See getChildByText(UiSelector, String, boolean)

Parameters
childPattern UiSelector selector for a child in a scrollable layout element
text String to find in the children of the childPattern match
Returns
  • UiObject representing the child element that matches the search conditions
Throws
UiObjectNotFoundException

public int getMaxSearchSwipes ()

Gets the maximum number of scrolls allowed when performing a scroll action in search of a child element. See getChildByDescription(UiSelector, String) and getChildByText(UiSelector, String) .

Returns
  • max the number of search swipes to perform until giving up

public double getSwipeDeadZonePercentage ()

Returns the percentage of a widget's size that's considered as a no-touch zone when swiping. The no-touch zone is set as a percentage of a widget's total width or height, denoting a margin around the swipable area of the widget. Swipes must start and end inside this margin. This is important when the widget being swiped may not respond to the swipe if started at a point too near to the edge. The default is 10% from either edge.

Returns
  • a value between 0 and 1

public boolean scrollBackward (int steps)

Performs a backward scroll. If the swipe direction is set to vertical, then the swipes will be performed from top to bottom. If the swipe direction is set to horizontal, then the swipes will be performed from left to right. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
steps number of steps. Use this to control the speed of the scroll action.
Returns
  • true if scrolled, false if can't scroll anymore
Throws
UiObjectNotFoundException

public boolean scrollBackward ()

Performs a backward scroll with the default number of scroll steps (55). If the swipe direction is set to vertical, then the swipes will be performed from top to bottom. If the swipe direction is set to horizontal, then the swipes will be performed from left to right. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
  • true if scrolled, and false if can't scroll anymore
Throws
UiObjectNotFoundException

public boolean scrollDescriptionIntoView (String text)

Performs a forward scroll action on the scrollable layout element until the content-description is found, or until swipe attempts have been exhausted. See setMaxSearchSwipes(int)

Parameters
text content-description to find within the contents of this scrollable layout element.
Returns
  • true if item is found; else, false
Throws
UiObjectNotFoundException

public boolean scrollForward ()

Performs a forward scroll with the default number of scroll steps (55). If the swipe direction is set to vertical, then the swipes will be performed from bottom to top. If the swipe direction is set to horizontal, then the swipes will be performed from right to left. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
  • true if scrolled, false if can't scroll anymore
Throws
UiObjectNotFoundException

public boolean scrollForward (int steps)

Performs a forward scroll. If the swipe direction is set to vertical, then the swipes will be performed from bottom to top. If the swipe direction is set to horizontal, then the swipes will be performed from right to left. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
steps number of steps. Use this to control the speed of the scroll action
Returns
  • true if scrolled, false if can't scroll anymore
Throws
UiObjectNotFoundException

public boolean scrollIntoView ( UiSelector selector)

Perform a scroll forward action to move through the scrollable layout element until a visible item that matches the selector is found. See scrollDescriptionIntoView(String) and scrollTextIntoView(String) .

Parameters
selector UiSelector selector
Returns
  • true if the item was found and now is in view; else, false
Throws
UiObjectNotFoundException

public boolean scrollIntoView ( UiObject obj)

Perform a forward scroll action to move through the scrollable layout element until a visible item that matches the UiObject is found.

Parameters
obj UiObject
Returns
  • true if the item was found and now is in view else false
Throws
UiObjectNotFoundException

public boolean scrollTextIntoView (String text)

Performs a forward scroll action on the scrollable layout element until the text you provided is visible, or until swipe attempts have been exhausted. See setMaxSearchSwipes(int)

Parameters
text test to look for
Returns
  • true if item is found; else, false
Throws
UiObjectNotFoundException

public boolean scrollToBeginning (int maxSwipes)

Scrolls to the beginning of a scrollable layout element. The beginning can be at the top-most edge in the case of vertical controls, or the left-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
  • true on scrolled else false
Throws
UiObjectNotFoundException

public boolean scrollToBeginning (int maxSwipes, int steps)

Scrolls to the beginning of a scrollable layout element. The beginning can be at the top-most edge in the case of vertical controls, or the left-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
steps use steps to control the speed, so that it may be a scroll, or fling
Returns
  • true on scrolled else false
Throws
UiObjectNotFoundException

public boolean scrollToEnd (int maxSwipes, int steps)

Scrolls to the end of a scrollable layout element. The end can be at the bottom-most edge in the case of vertical controls, or the right-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
steps use steps to control the speed, so that it may be a scroll, or fling
Returns
  • true on scrolled else false
Throws
UiObjectNotFoundException

public boolean scrollToEnd (int maxSwipes)

Scrolls to the end of a scrollable layout element. The end can be at the bottom-most edge in the case of vertical controls, or the right-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
  • true on scrolled, else false
Throws
UiObjectNotFoundException

public UiScrollable setAsHorizontalList ()

Set the direction of swipes to be horizontal when performing scroll actions.

Returns
  • reference to itself

public UiScrollable setAsVerticalList ()

Set the direction of swipes to be vertical when performing scroll actions.

Returns
  • reference to itself

public UiScrollable setMaxSearchSwipes (int swipes)

Sets the maximum number of scrolls allowed when performing a scroll action in search of a child element. See getChildByDescription(UiSelector, String) and getChildByText(UiSelector, String) .

Parameters
swipes the number of search swipes to perform until giving up
Returns
  • reference to itself

public UiScrollable setSwipeDeadZonePercentage (double swipeDeadZonePercentage)

Sets the percentage of a widget's size that's considered as no-touch zone when swiping. The no-touch zone is set as percentage of a widget's total width or height, denoting a margin around the swipable area of the widget. Swipes must always start and end inside this margin. This is important when the widget being swiped may not respond to the swipe if started at a point too near to the edge. The default is 10% from either edge.

Parameters
swipeDeadZonePercentage is a value between 0 and 1
Returns
  • reference to itself

Protected Methods

protected boolean exists ( UiSelector selector)

Used privately when performing swipe searches to decide if an element has become visible or not.

Returns
  • true if found else false