to top

UiScrollable

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

Summary

Public Constructors
UiScrollable(UiSelector container)
UiScrollable is a UiCollection and as such requires a UiSelector to identify the container UI element of the scrollable collection.
Public Methods
boolean flingBackward()
See scrollBackward(int)
boolean flingForward()
A convenience version of scrollForward(int), performs a fling
boolean flingToBeginning(int maxSwipes)
See scrollToBeginning(int, int)
boolean flingToEnd(int maxSwipes)
See scrollToEnd(int, int)
UiObject getChildByDescription(UiSelector childPattern, String text, boolean allowScrollSearch)
See getChildByDescription(UiSelector, String)
UiObject getChildByDescription(UiSelector childPattern, String text)
Searches for child UI element within the constraints of this UiScrollable UiSelector container.
UiObject getChildByInstance(UiSelector childPattern, int instance)
Searches for child UI element within the constraints of this UiScrollable UiSelector selector.
UiObject getChildByText(UiSelector childPattern, String text, boolean allowScrollSearch)
See getChildByText(UiSelector, String)
UiObject getChildByText(UiSelector childPattern, String text)
Searches for child UI element within the constraints of this UiScrollable UiSelector container.
int getMaxSearchSwipes()
#getChildByDescription(String, boolean) and #getChildByText(String, boolean) use an arguments that specifies if scrolling is allowed while searching for the UI 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)
Perform a scroll backward.
boolean scrollBackward()
See scrollBackward(int)
boolean scrollDescriptionIntoView(String text)
Performs a swipe Up on the UI element until the requested content-description is visible or until swipe attempts have been exhausted.
boolean scrollForward()
A convenience version of scrollForward(int), performs a regular scroll
boolean scrollForward(int steps)
Perform a scroll forward.
boolean scrollIntoView(UiSelector selector)
Perform a scroll search for a UI element matching the UiSelector selector argument.
boolean scrollTextIntoView(String text)
Performs a swipe up on the UI element until the requested text is visible or until swipe attempts have been exhausted.
boolean scrollToBeginning(int maxSwipes)
See scrollToBeginning(int, int)
boolean scrollToBeginning(int maxSwipes, int steps)
Scrolls to the beginning of a scrollable UI element.
boolean scrollToEnd(int maxSwipes, int steps)
Scrolls to the end of a scrollable UI element.
boolean scrollToEnd(int maxSwipes)
See {@link UiScrollable#scrollToEnd(int, int)
void setAsHorizontalList()
Set the direction of swipes when performing scroll search
void setAsVerticalList()
Set the direction of swipes when performing scroll search
void setMaxSearchSwipes(int swipes)
#getChildByDescription(String, boolean) and #getChildByText(String, boolean) use an arguments that specifies if scrolling is allowed while searching for the UI element.
void setSwipeDeadZonePercentage(double swipeDeadZonePercentage)
Sets the percentage of a widget's size that's considered as a no touch zone when swiping.
[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)

UiScrollable is a UiCollection and as such requires a UiSelector to identify the container UI element of the scrollable collection. Further operations on the items in the container will require specifying UiSelector as an item selector.

Parameters
container a UiSelector selector

Public Methods

public boolean flingBackward ()

See scrollBackward(int)

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

public boolean flingForward ()

A convenience version of scrollForward(int), performs a fling

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

public boolean flingToBeginning (int maxSwipes)

See scrollToBeginning(int, int)

Returns
  • true on scrolled else false
Throws
UiObjectNotFoundException

public boolean flingToEnd (int maxSwipes)

See scrollToEnd(int, int)

Returns
  • true on scrolled else false
Throws
UiObjectNotFoundException

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

See getChildByDescription(UiSelector, String)

Parameters
childPattern UiSelector selector of the child pattern to match and return
text String may be a partial match for the content-description of a child element.
allowScrollSearch set to true if scrolling is allowed
Returns
  • UiObject pointing at and instance of childPattern
Throws
UiObjectNotFoundException

public UiObject getChildByDescription (UiSelector childPattern, String text)

Searches for child UI element within the constraints of this UiScrollable UiSelector container. It looks for any child matching the childPattern argument within its hierarchy with a matching content-description text. The returned UiObject will represent the UI element matching the childPattern and not the sub element that matched the content description.

By default this operation will perform scroll search while attempting to find the UI element See getChildByDescription(UiSelector, String, boolean)

Parameters
childPattern UiSelector selector of the child pattern to match and return
text String of the identifying child contents of of the childPattern
Returns
  • UiObject pointing at and instance of childPattern
Throws
UiObjectNotFoundException

public UiObject getChildByInstance (UiSelector childPattern, int instance)

Searches for child UI element within the constraints of this UiScrollable UiSelector selector. It looks for any child matching the childPattern argument and return the instance specified. The operation is performed only on the visible items and no scrolling is performed in this case.

Parameters
childPattern UiSelector selector of the child pattern to match and return
instance int the desired matched instance of this childPattern
Returns
  • UiObject pointing at and instance of childPattern
Throws
UiObjectNotFoundException

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

See getChildByText(UiSelector, String)

Parameters
childPattern UiSelector selector of the child pattern to match and return
text String of the identifying child contents of of the childPattern
allowScrollSearch set to true if scrolling is allowed
Returns
  • UiObject pointing at and instance of childPattern
Throws
UiObjectNotFoundException

public UiObject getChildByText (UiSelector childPattern, String text)

Searches for child UI element within the constraints of this UiScrollable UiSelector container. It looks for any child matching the childPattern argument that has a sub UI element anywhere within its sub hierarchy that has text attribute text. The returned UiObject will point at the childPattern instance that matched the search and not at the text matched sub element

By default this operation will perform scroll search while attempting to find the UI element. See getChildByText(UiSelector, String, boolean)

Parameters
childPattern UiSelector selector of the child pattern to match and return
text String of the identifying child contents of of the childPattern
Returns
  • UiObject pointing at and instance of childPattern
Throws
UiObjectNotFoundException

public int getMaxSearchSwipes ()

#getChildByDescription(String, boolean) and #getChildByText(String, boolean) use an arguments that specifies if scrolling is allowed while searching for the UI element. The number of scrolls currently allowed to perform a search can be read by this method. See setMaxSearchSwipes(int)

Returns
  • max value of the number of swipes currently allowed during a scroll search

public double getSwipeDeadZonePercentage ()

Returns the percentage of a widget's size that's considered as a no touch zone when swiping. Dead zones are set as 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)

Perform a scroll backward. If this list is set to vertical (see setAsVerticalList() default) then the swipes will be executed from the top to bottom. If this list is set to horizontal (see setAsHorizontalList()) then the swipes will be executed from the left to right. Caution is required on 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 if scrolled and false if the control can't scroll anymore
Throws
UiObjectNotFoundException

public boolean scrollBackward ()

See scrollBackward(int)

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

public boolean scrollDescriptionIntoView (String text)

Performs a swipe Up on the UI element until the requested content-description is visible or until swipe attempts have been exhausted. See setMaxSearchSwipes(int)

Parameters
text to look for anywhere within the contents of this scrollable.
Returns
  • true if item us found else false
Throws
UiObjectNotFoundException

public boolean scrollForward ()

A convenience version of scrollForward(int), performs a regular scroll

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

public boolean scrollForward (int steps)

Perform a scroll forward. If this list is set to vertical (see setAsVerticalList() default) then the swipes will be executed from the bottom to top. If this list is set to horizontal (see setAsHorizontalList()) then the swipes will be executed from the right to left. Caution is required on 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 if scrolled and false if the control can't scroll anymore
Throws
UiObjectNotFoundException

public boolean scrollIntoView (UiSelector selector)

Perform a scroll search for a UI element matching the UiSelector selector argument. 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 scrollTextIntoView (String text)

Performs a swipe up on the UI element until the requested text is visible or until swipe attempts have been exhausted. See setMaxSearchSwipes(int)

Parameters
text to look for
Returns
  • true if item us found else false
Throws
UiObjectNotFoundException

public boolean scrollToBeginning (int maxSwipes)

See scrollToBeginning(int, int)

Returns
  • true on scrolled else false
Throws
UiObjectNotFoundException

public boolean scrollToBeginning (int maxSwipes, int steps)

Scrolls to the beginning of a scrollable UI element. The beginning could be the top most in case of vertical lists or the left most in case of horizontal lists. Caution is required on 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 UI element. The end could be the bottom most in case of vertical controls or the right most for horizontal controls. Caution is required on 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)

See {@link UiScrollable#scrollToEnd(int, int)

Returns
  • true on scrolled else false
Throws
UiObjectNotFoundException

public void setAsHorizontalList ()

Set the direction of swipes when performing scroll search

public void setAsVerticalList ()

Set the direction of swipes when performing scroll search

public void setMaxSearchSwipes (int swipes)

#getChildByDescription(String, boolean) and #getChildByText(String, boolean) use an arguments that specifies if scrolling is allowed while searching for the UI element. The number of scrolls allowed to perform a search can be modified by this method. The current value can be read by calling getMaxSearchSwipes()

Parameters
swipes is the number of search swipes until abort

public void setSwipeDeadZonePercentage (double swipeDeadZonePercentage)

Sets the percentage of a widget's size that's considered as a no touch zone when swiping. Dead zones are 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