UiScrollable

Artifact: androidx.test.uiautomator:uiautomator

Added in 2.2.0

Kotlin |Java

class UiScrollable : UiCollection

kotlin.Any
↳	androidx.test.uiautomator.UiObject
	↳	androidx.test.uiautomator.UiCollection
		↳	androidx.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

Public constructors
`UiScrollable(container: UiSelector)` Constructor.

Public functions
`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(maxSwipes: Int)` Performs a fling gesture to reach the beginning of a scrollable layout element.
`Boolean`	`flingToEnd(maxSwipes: Int)` Performs a fling gesture to reach the end of a scrollable layout element.
`UiObject`	`getChildByDescription(childPattern: UiSelector, text: String)` Searches for a child element in the present scrollable container.
`UiObject`	`getChildByDescription( childPattern: UiSelector, text: String, allowScrollSearch: Boolean )` Searches for a child element in the present scrollable container.
`UiObject`	`getChildByInstance(childPattern: UiSelector, instance: Int)` Searches for a child element in the present scrollable container that matches the selector you provided.
`UiObject`	`getChildByText(childPattern: UiSelector, text: String)` Searches for a child element in the present scrollable container.
`UiObject`	`getChildByText( childPattern: UiSelector, text: String, allowScrollSearch: Boolean )` 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()` Performs a backward scroll with the default number of scroll steps (55).
`Boolean`	`scrollBackward(steps: Int)` Performs a backward scroll.
`Boolean`	`scrollDescriptionIntoView(text: String)` 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(steps: Int)` Performs a forward scroll.
`Boolean`	`scrollIntoView(obj: UiObject)` Perform a forward scroll action to move through the scrollable layout element until a visible item that matches the `UiObject` is found.
`Boolean`	`scrollIntoView(selector: UiSelector)` Perform a scroll forward action to move through the scrollable layout element until a visible item that matches the selector is found.
`Boolean`	`scrollTextIntoView(text: String)` 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(maxSwipes: Int)` Scrolls to the beginning of a scrollable layout element.
`Boolean`	`scrollToBeginning(maxSwipes: Int, steps: Int)` Scrolls to the beginning of a scrollable layout element.
`Boolean`	`scrollToEnd(maxSwipes: Int)` Scrolls to the end of a scrollable layout element.
`Boolean`	`scrollToEnd(maxSwipes: Int, steps: Int)` 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(swipes: Int)` Sets the maximum number of scrolls allowed when performing a scroll action in search of a child element.
`UiScrollable`	`setSwipeDeadZonePercentage(swipeDeadZonePercentage: Double)` Sets the percentage of a widget's size that's considered as no-touch zone when swiping.

Protected functions
`Boolean`	`exists(selector: UiSelector)` Used privately when performing swipe searches to decide if an element has become visible or not.

Inherited Constants

From androidx.test.uiautomator.UiObject

`const Int`	`FINGER_TOUCH_HALF_WIDTH = 20`
`const Int`	`SWIPE_MARGIN_LIMIT = 5`
`const Long`	`WAIT_FOR_EVENT_TMEOUT = 3000` This property is deprecated. use `setScrollAcknowledgmentTimeout`
`const Long`	`WAIT_FOR_SELECTOR_POLL = 1000`
`const Long`	`WAIT_FOR_SELECTOR_TIMEOUT = 10000` This property is deprecated. use `setWaitForSelectorTimeout`
`const Long`	`WAIT_FOR_WINDOW_TMEOUT = 5500`

Inherited functions

From androidx.test.uiautomator.UiCollection

Int

getChildCount(childPattern: UiSelector)

Counts child UI element instances matching the childPattern argument.

From androidx.test.uiautomator.UiObject

`Unit`	`clearTextField()` Clears the existing text contents in an editable field.
`Boolean`	`click()` Performs a click at the center of the visible bounds of the UI element represented by this UiObject.
`Boolean`	`clickAndWaitForNewWindow()` Waits for window transitions that would typically take longer than the usual default timeouts.
`Boolean`	`clickAndWaitForNewWindow(timeout: Long)` Performs a click at the center of the visible bounds of the UI element represented by this UiObject and waits for window transitions.
`Boolean`	`clickBottomRight()` Clicks the bottom and right corner of the UI element
`Boolean`	`clickTopLeft()` Clicks the top and left corner of the UI element
`Boolean`	`dragTo(destObj: UiObject, steps: Int)` Drags this object to a destination UiObject.
`Boolean`	`dragTo(destX: Int, destY: Int, steps: Int)` Drags this object to arbitrary coordinates.
`Boolean`	`exists()` Check if view exists.
`AccessibilityNodeInfo?`	`findAccessibilityNodeInfo(timeout: Long)` Finds a matching UI element in the accessibility hierarchy, by using the selector for this UiObject.
`Rect`	`getBounds()` Returns the view's `bounds` property.
`UiObject`	`getChild(selector: UiSelector)` Creates a new UiObject for a child view that is under the present UiObject.
`Int`	`getChildCount()` Counts the child views immediately under the present UiObject.
`String`	`getClassName()` Retrieves the `className` property of the UI element.
`String`	`getContentDescription()` Reads the `content_desc` property of the UI element
`UiObject`	`getFromParent(selector: UiSelector)` Creates a new UiObject for a sibling view or a child of the sibling view, relative to the present UiObject.
`String`	`getPackageName()` Reads the view's `package` property
`UiSelector`	`getSelector()` Debugging helper.
`String`	`getText()` Reads the `text` property of the UI element
`Rect`	`getVisibleBounds()` Returns the visible bounds of the view.
`Boolean`	`isCheckable()` Checks if the UI element's `checkable` property is currently true.
`Boolean`	`isChecked()` Check if the UI element's `checked` property is currently true
`Boolean`	`isClickable()` Checks if the UI element's `clickable` property is currently true.
`Boolean`	`isEnabled()` Checks if the UI element's `enabled` property is currently true.
`Boolean`	`isFocusable()` Check if the UI element's `focusable` property is currently true.
`Boolean`	`isFocused()` Check if the UI element's `focused` property is currently true
`Boolean`	`isLongClickable()` Check if the view's `long-clickable` property is currently true
`Boolean`	`isScrollable()` Check if the view's `scrollable` property is currently true
`Boolean`	`isSelected()` Checks if the UI element's `selected` property is currently true.
`Boolean`	`longClick()` Long clicks the center of the visible bounds of the UI element
`Boolean`	`longClickBottomRight()` Long clicks bottom and right corner of the UI element
`Boolean`	`longClickTopLeft()` Long clicks on the top and left corner of the UI element
`Boolean`	`performMultiPointerGesture( touches: Array<Array<MotionEvent.PointerCoords!>!> )` Performs a multi-touch gesture.
`Boolean`	`performTwoPointerGesture( startPoint1: Point, startPoint2: Point, endPoint1: Point, endPoint2: Point, steps: Int )` Generates a two-pointer gesture with arbitrary starting and ending points.
`Boolean`	`pinchIn(percent: Int, steps: Int)` Performs a two-pointer gesture, where each pointer moves diagonally toward the other, from the edges to the center of this UiObject .
`Boolean`	`pinchOut(percent: Int, steps: Int)` Performs a two-pointer gesture, where each pointer moves diagonally opposite across the other, from the center out towards the edges of the this UiObject.
`Boolean`	`setText(text: String?)` Sets the text in an editable field, after clearing the field's content.
`Boolean`	`swipeDown(steps: Int)` Performs the swipe down action on the UiObject.
`Boolean`	`swipeLeft(steps: Int)` Performs the swipe left action on the UiObject.
`Boolean`	`swipeRight(steps: Int)` Performs the swipe right action on the UiObject.
`Boolean`	`swipeUp(steps: Int)` Performs the swipe up action on the UiObject.
`Boolean`	`waitForExists(timeout: Long)` Waits a specified length of time for a view to become visible.
`Boolean`	`waitUntilGone(timeout: Long)` Waits a specified length of time for a view to become undetectable.

Public constructors

UiScrollable

Added in 2.2.0

UiScrollable(container: UiSelector)

Constructor.

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

Public functions

flingBackward

Added in 2.2.0

fun flingBackward(): Boolean

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
`androidx.test.uiautomator.UiObjectNotFoundException`

flingForward

Added in 2.2.0

fun flingForward(): Boolean

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
`androidx.test.uiautomator.UiObjectNotFoundException`

flingToBeginning

Added in 2.2.0

fun flingToBeginning(maxSwipes: Int): Boolean

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.

Parameters
`maxSwipes: Int`	maximum number of flings allowed

Returns
`Boolean`	true if beginning reached within maxSwipes

Throws
`androidx.test.uiautomator.UiObjectNotFoundException`

flingToEnd

Added in 2.2.0

fun flingToEnd(maxSwipes: Int): Boolean

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.

Parameters
`maxSwipes: Int`	maximum number of flings allowed

Returns
`Boolean`	true if end reached within maxSwipes

Throws
`androidx.test.uiautomator.UiObjectNotFoundException`

getChildByDescription

fun getChildByDescription(childPattern: UiSelector, text: String): UiObject

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

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
`androidx.test.uiautomator.UiObjectNotFoundException`

getChildByDescription

Added in 2.2.0

fun getChildByDescription(
    childPattern: UiSelector,
    text: String,
    allowScrollSearch: Boolean
): UiObject

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
`androidx.test.uiautomator.UiObjectNotFoundException`

getChildByInstance

fun getChildByInstance(childPattern: UiSelector, instance: Int): UiObject

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
`androidx.test.uiautomator.UiObjectNotFoundException`

getChildByText

fun getChildByText(childPattern: UiSelector, text: String): UiObject

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

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
`androidx.test.uiautomator.UiObjectNotFoundException`

getChildByText

Added in 2.2.0

fun getChildByText(
    childPattern: UiSelector,
    text: String,
    allowScrollSearch: Boolean
): UiObject

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
`androidx.test.uiautomator.UiObjectNotFoundException`

getMaxSearchSwipes

Added in 2.2.0

fun getMaxSearchSwipes(): Int

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

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

getSwipeDeadZonePercentage

Added in 2.2.0

fun getSwipeDeadZonePercentage(): Double

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

Added in 2.2.0

fun scrollBackward(): Boolean

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
`androidx.test.uiautomator.UiObjectNotFoundException`

scrollBackward

Added in 2.2.0

fun scrollBackward(steps: Int): Boolean

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
`androidx.test.uiautomator.UiObjectNotFoundException`

scrollDescriptionIntoView

Added in 2.2.0

fun scrollDescriptionIntoView(text: String): Boolean

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

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
`androidx.test.uiautomator.UiObjectNotFoundException`

scrollForward

Added in 2.2.0

fun scrollForward(): Boolean

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
`androidx.test.uiautomator.UiObjectNotFoundException`

scrollForward

Added in 2.2.0

fun scrollForward(steps: Int): Boolean

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
`androidx.test.uiautomator.UiObjectNotFoundException`

scrollIntoView

Added in 2.2.0

fun scrollIntoView(obj: UiObject): Boolean

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
`androidx.test.uiautomator.UiObjectNotFoundException`

scrollIntoView

Added in 2.2.0

fun scrollIntoView(selector: UiSelector): Boolean

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

Parameters
`selector: UiSelector`	`UiSelector` selector

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

Throws
`androidx.test.uiautomator.UiObjectNotFoundException`

scrollTextIntoView

Added in 2.2.0

fun scrollTextIntoView(text: String): Boolean

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

Parameters
`text: String`	test to look for

Returns
`Boolean`	true if item is found; else, false

Throws
`androidx.test.uiautomator.UiObjectNotFoundException`

scrollToBeginning

Added in 2.2.0

fun scrollToBeginning(maxSwipes: Int): Boolean

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`	maximum number of scrolls allowed

Returns
`Boolean`	true if beginning reached within maxSwipes

Throws
`androidx.test.uiautomator.UiObjectNotFoundException`

scrollToBeginning

Added in 2.2.0

fun scrollToBeginning(maxSwipes: Int, steps: Int): Boolean

Parameters
`maxSwipes: Int`	maximum number of scrolls allowed
`steps: Int`	use steps to control the speed, so that it may be a scroll, or fling

Returns
`Boolean`	true if beginning reached within maxSwipes

Throws
`androidx.test.uiautomator.UiObjectNotFoundException`

scrollToEnd

Added in 2.2.0

fun scrollToEnd(maxSwipes: Int): Boolean

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`	maximum number of scrolls allowed

Returns
`Boolean`	true if end reached within maxSwipes

Throws
`androidx.test.uiautomator.UiObjectNotFoundException`

scrollToEnd

Added in 2.2.0

fun scrollToEnd(maxSwipes: Int, steps: Int): Boolean

Parameters
`maxSwipes: Int`	maximum number of scrolls allowed
`steps: Int`	use steps to control the speed, so that it may be a scroll, or fling

Returns
`Boolean`	true if end reached within maxSwipes

Throws
`androidx.test.uiautomator.UiObjectNotFoundException`

setAsHorizontalList

Added in 2.2.0

fun setAsHorizontalList(): UiScrollable

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

Returns
`UiScrollable`	reference to itself

setAsVerticalList

Added in 2.2.0

fun setAsVerticalList(): UiScrollable

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

Returns
`UiScrollable`	reference to itself

setMaxSearchSwipes

Added in 2.2.0

fun setMaxSearchSwipes(swipes: Int): UiScrollable

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

Parameters
`swipes: Int`	the number of search swipes to perform until giving up

Returns
`UiScrollable`	reference to itself

setSwipeDeadZonePercentage

Added in 2.2.0

fun setSwipeDeadZonePercentage(swipeDeadZonePercentage: Double): UiScrollable

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 functions

exists

Added in 2.2.0

protected fun exists(selector: UiSelector): Boolean

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

Parameters
`selector: UiSelector`

Returns
`Boolean`	true if found else false