UiScrollable

public class UiScrollable
extends UiCollection

java.lang.Object
   ↳ android.support.test.uiautomator.UiObject
     ↳ android.support.test.uiautomator.UiCollection
       ↳ android.support.test.uiautomator.UiScrollable


UiScrollable is a UiCollection and provides support for searching for items in scrollable layout elements. This class can be used with horizontally or vertically scrollable controls.

Summary

Inherited constants

From class android.support.test.uiautomator.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)

Searches for a child element in the present scrollable container.

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

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(int steps)

Performs a forward scroll.

boolean scrollForward()

Performs a forward scroll with the default number of scroll steps (55).

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)

Scrolls to the end of a scrollable layout element.

boolean scrollToEnd(int maxSwipes, int steps)

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.

Inherited methods

From class android.support.test.uiautomator.UiCollection
From class android.support.test.uiautomator.UiObject
From class java.lang.Object

Public constructors

UiScrollable

UiScrollable (UiSelector container)

Constructor.

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

Public methods

flingBackward

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
boolean true if scrolled, and false if can't scroll anymore

Throws
UiObjectNotFoundException

flingForward

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
boolean true if scrolled, false if can't scroll anymore

Throws
UiObjectNotFoundException

flingToBeginning

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
boolean true on scrolled else false

Throws
UiObjectNotFoundException

flingToEnd

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
boolean true on scrolled, else false

Throws
UiObjectNotFoundException

getChildByDescription

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: UiSelector for a child in a scollable layout element

text String: Content-description to find in the children of the childPattern match

Returns
UiObject UiObject representing the child element that matches the search conditions

Throws
UiObjectNotFoundException
UiObjectNotFoundException

getChildByDescription

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: UiSelector for a child in a scollable layout element

text String: Content-description to find in the children of the childPattern match (may be a partial match)

allowScrollSearch boolean: set to true if scrolling is allowed

Returns
UiObject UiObject representing the child element that matches the search conditions

Throws
UiObjectNotFoundException
UiObjectNotFoundException

getChildByInstance

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: UiSelector for a child in a scollable layout element

instance int: int number representing the occurance of a childPattern match

Returns
UiObject UiObject representing the child element that matches the search conditions

Throws
UiObjectNotFoundException

getChildByText

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: UiSelector selector for a child in a scrollable layout element

text String: String to find in the children of the childPattern match

allowScrollSearch boolean: set to true if scrolling is allowed

Returns
UiObject UiObject representing the child element that matches the search conditions

Throws
UiObjectNotFoundException
UiObjectNotFoundException

getChildByText

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: UiSelector selector for a child in a scrollable layout element

text String: String to find in the children of the childPattern match

Returns
UiObject UiObject representing the child element that matches the search conditions

Throws
UiObjectNotFoundException
UiObjectNotFoundException

getMaxSearchSwipes

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
int max the number of search swipes to perform until giving up

getSwipeDeadZonePercentage

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
double a value between 0 and 1

scrollBackward

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 int: number of steps. Use this to control the speed of the scroll action.

Returns
boolean true if scrolled, false if can't scroll anymore

Throws
UiObjectNotFoundException

scrollBackward

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
boolean true if scrolled, and false if can't scroll anymore

Throws
UiObjectNotFoundException

scrollDescriptionIntoView

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 String: content-description to find within the contents of this scrollable layout element.

Returns
boolean true if item is found; else, false

Throws
UiObjectNotFoundException

scrollForward

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 int: number of steps. Use this to control the speed of the scroll action

Returns
boolean true if scrolled, false if can't scroll anymore

Throws
UiObjectNotFoundException

scrollForward

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
boolean true if scrolled, false if can't scroll anymore

Throws
UiObjectNotFoundException

scrollIntoView

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: UiSelector selector

Returns
boolean true if the item was found and now is in view; else, false

Throws
UiObjectNotFoundException

scrollIntoView

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: UiObject

Returns
boolean true if the item was found and now is in view else false

Throws
UiObjectNotFoundException

scrollTextIntoView

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 String: test to look for

Returns
boolean true if item is found; else, false

Throws
UiObjectNotFoundException

scrollToBeginning

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
boolean true on scrolled else false

Throws
UiObjectNotFoundException

scrollToBeginning

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
maxSwipes int

steps int: use steps to control the speed, so that it may be a scroll, or fling

Returns
boolean true on scrolled else false

Throws
UiObjectNotFoundException

scrollToEnd

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
boolean true on scrolled, else false

Throws
UiObjectNotFoundException

scrollToEnd

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
maxSwipes int

steps int: use steps to control the speed, so that it may be a scroll, or fling

Returns
boolean true on scrolled else false

Throws
UiObjectNotFoundException

setAsHorizontalList

UiScrollable setAsHorizontalList ()

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

Returns
UiScrollable reference to itself

setAsVerticalList

UiScrollable setAsVerticalList ()

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

Returns
UiScrollable reference to itself

setMaxSearchSwipes

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 int: the number of search swipes to perform until giving up

Returns
UiScrollable reference to itself

setSwipeDeadZonePercentage

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 double: is a value between 0 and 1

Returns
UiScrollable reference to itself

Protected methods

exists

boolean exists (UiSelector selector)

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

Returns
boolean true if found else false