Gradle dependencies
compile group: 'androidx.test.uiautomator', name: 'uiautomator', version: '2.2.0'
- groupId: androidx.test.uiautomator
- artifactId: uiautomator
- version: 2.2.0
Artifact androidx.test.uiautomator:uiautomator:2.2.0 it located at Google repository (https://maven.google.com/)
Androidx artifact mapping:
androidx.test.uiautomator:uiautomator com.android.support.test.uiautomator:uiautomator
Androidx class mapping:
androidx.test.uiautomator.UiScrollable android.support.test.uiautomator.UiScrollable
Overview
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
Methods |
---|
public boolean | ensureFullyVisible(UiObject childObject)
Scrolls forward until the UiObject is fully visible in the scrollable container. |
protected boolean | exists(UiSelector selector)
Used privately when performing swipe searches to decide if an element has become
visible or not. |
public boolean | flingBackward()
Performs a backwards fling action with the default number of fling
steps (5). |
public boolean | flingForward()
Performs a forward fling with the default number of fling steps (5). |
public boolean | flingToBeginning(int maxSwipes)
Performs a fling gesture to reach the beginning of a scrollable layout element. |
public boolean | flingToEnd(int maxSwipes)
Performs a fling gesture to reach the end of a scrollable layout element. |
public UiObject | getChildByDescription(UiSelector childPattern, java.lang.String text)
Searches for a child element in the present scrollable container. |
public UiObject | getChildByDescription(UiSelector childPattern, java.lang.String text, boolean allowScrollSearch)
Searches for a child element in the present scrollable container. |
public UiObject | getChildByInstance(UiSelector childPattern, int instance)
Searches for a child element in the present scrollable container that
matches the selector you provided. |
public UiObject | getChildByText(UiSelector childPattern, java.lang.String text)
Searches for a child element in the present scrollable
container. |
public UiObject | getChildByText(UiSelector childPattern, java.lang.String text, boolean allowScrollSearch)
Searches for a child element in the present scrollable container. |
public int | getMaxSearchSwipes()
Gets the maximum number of scrolls allowed when performing a
scroll action in search of a child element. |
public double | getSwipeDeadZonePercentage()
Returns the percentage of a widget's size that's considered as a no-touch
zone when swiping. |
public boolean | scrollBackward()
Performs a backward scroll with the default number of scroll steps (55). |
public boolean | scrollBackward(int steps)
Performs a backward scroll. |
public boolean | scrollDescriptionIntoView(java.lang.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. |
public boolean | scrollForward()
Performs a forward scroll with the default number of scroll steps (55). |
public boolean | scrollForward(int steps)
Performs a forward scroll. |
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. |
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. |
public boolean | scrollTextIntoView(java.lang.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. |
public boolean | scrollToBeginning(int maxSwipes)
Scrolls to the beginning of a scrollable layout element. |
public boolean | scrollToBeginning(int maxSwipes, int steps)
Scrolls to the beginning of a scrollable layout element. |
public boolean | scrollToEnd(int maxSwipes)
Scrolls to the end of a scrollable layout element. |
public boolean | scrollToEnd(int maxSwipes, int steps)
Scrolls to the end of a scrollable layout element. |
public UiScrollable | setAsHorizontalList()
Set the direction of swipes to be horizontal when performing scroll actions. |
public UiScrollable | setAsVerticalList()
Set the direction of swipes to be vertical when performing scroll actions. |
public UiScrollable | setMaxSearchSwipes(int swipes)
Sets the maximum number of scrolls allowed when performing a
scroll action in search of a child element. |
public UiScrollable | setSwipeDeadZonePercentage(double swipeDeadZonePercentage)
Sets the percentage of a widget's size that's considered as no-touch
zone when swiping. |
from UiCollection | getChildCount |
from UiObject | clearTextField, click, clickAndWaitForNewWindow, clickAndWaitForNewWindow, clickBottomRight, clickTopLeft, dragTo, dragTo, exists, findAccessibilityNodeInfo, getBounds, getChild, getChildCount, getClassName, getContentDescription, getFromParent, getPackageName, getSelector, getText, getVisibleBounds, isCheckable, isChecked, isClickable, isEnabled, isFocusable, isFocused, isLongClickable, isScrollable, isSelected, legacySetText, longClick, longClickBottomRight, longClickTopLeft, performMultiPointerGesture, performTwoPointerGesture, pinchIn, pinchOut, setText, swipeDown, swipeLeft, swipeRight, swipeUp, waitForExists, waitUntilGone |
from java.lang.Object | clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructors
Constructor.
Parameters:
container: a UiSelector selector to identify the scrollable
layout element.
Since: API Level 16
Methods
Set the direction of swipes to be vertical when performing scroll actions.
Returns:
reference to itself
Since: API Level 16
Set the direction of swipes to be horizontal when performing scroll actions.
Returns:
reference to itself
Since: API Level 16
Used privately when performing swipe searches to decide if an element has become
visible or not.
Parameters:
selector:
Returns:
true if found else false
Since: API Level 16
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 UiScrollable.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
Since: API Level 16
public
UiObject getChildByDescription(
UiSelector childPattern, java.lang.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
Since: API Level 16
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
Since: API Level 16
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 UiScrollable.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
Since: API Level 16
public
UiObject getChildByText(
UiSelector childPattern, java.lang.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
Since: API Level 16
public boolean
scrollDescriptionIntoView(java.lang.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 UiScrollable.setMaxSearchSwipes(int)
Parameters:
text: content-description to find within the contents of this scrollable layout element.
Returns:
true if item is found; else, false
Since: API Level 16
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
Since: API Level 16
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 UiScrollable.scrollDescriptionIntoView(String) and UiScrollable.scrollTextIntoView(String).
Parameters:
selector: UiSelector selector
Returns:
true if the item was found and now is in view; else, false
Since: API Level 16
public boolean
ensureFullyVisible(
UiObject childObject)
Scrolls forward until the UiObject is fully visible in the scrollable container.
Use this method to make sure that the child item's edges are not offscreen.
Parameters:
childObject: UiObject representing the child element
Returns:
true if the child element is already fully visible, or
if the method scrolled successfully until the child became fully visible;
otherwise, false if the attempt to scroll failed.
public boolean
scrollTextIntoView(java.lang.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 UiScrollable.setMaxSearchSwipes(int)
Parameters:
text: test to look for
Returns:
true if item is found; else, false
Since: API Level 16
Sets the maximum number of scrolls allowed when performing a
scroll action in search of a child element.
See UiScrollable.getChildByDescription(UiSelector, String) and
UiScrollable.getChildByText(UiSelector, String).
Parameters:
swipes: the number of search swipes to perform until giving up
Returns:
reference to itself
Since: API Level 16
public int
getMaxSearchSwipes()
Gets the maximum number of scrolls allowed when performing a
scroll action in search of a child element.
See UiScrollable.getChildByDescription(UiSelector, String) and
UiScrollable.getChildByText(UiSelector, String).
Returns:
max the number of search swipes to perform until giving up
Since: API Level 16
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
Since: API Level 16
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
Since: API Level 16
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
Since: API Level 16
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
Since: API Level 16
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
Since: API Level 16
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
Since: API Level 16
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
Since: API Level 16
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.
Parameters:
maxSwipes:
Returns:
true on scrolled else false
Since: API Level 16
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.
Parameters:
maxSwipes:
Returns:
true on scrolled else false
Since: API Level 16
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
Since: API Level 16
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.
Parameters:
maxSwipes:
Returns:
true on scrolled, else false
Since: API Level 16
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.
Parameters:
maxSwipes:
Returns:
true on scrolled, else false
Since: API Level 16
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
Since: API Level 16
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
Since: API Level 16
Source
/*
* Copyright (C) 2012 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.test.uiautomator;
import android.graphics.Rect;
import android.util.Log;
import android.view.accessibility.AccessibilityNodeInfo;
/**
* UiScrollable is a {@link UiCollection} and provides support for searching
* for items in scrollable layout elements. This class can be used with
* horizontally or vertically scrollable controls.
* @since API Level 16
*/
public class UiScrollable extends UiCollection {
private static final String LOG_TAG = UiScrollable.class.getSimpleName();
// More steps slows the swipe and prevents contents from being flung too far
private static final int SCROLL_STEPS = 55;
private static final int FLING_STEPS = 5;
// Restrict a swipe's starting and ending points inside a 10% margin of the target
private static final double DEFAULT_SWIPE_DEADZONE_PCT = 0.1;
// Limits the number of swipes/scrolls performed during a search
private static int mMaxSearchSwipes = 30;
// Used in ScrollForward() and ScrollBackward() to determine swipe direction
private boolean mIsVerticalList = true;
private double mSwipeDeadZonePercentage = DEFAULT_SWIPE_DEADZONE_PCT;
/**
* Constructor.
*
* @param container a {@link UiSelector} selector to identify the scrollable
* layout element.
* @since API Level 16
*/
public UiScrollable(UiSelector container) {
// wrap the container selector with container so that QueryController can handle
// this type of enumeration search accordingly
super(container);
}
/**
* Set the direction of swipes to be vertical when performing scroll actions.
* @return reference to itself
* @since API Level 16
*/
public UiScrollable setAsVerticalList() {
Tracer.trace();
mIsVerticalList = true;
return this;
}
/**
* Set the direction of swipes to be horizontal when performing scroll actions.
* @return reference to itself
* @since API Level 16
*/
public UiScrollable setAsHorizontalList() {
Tracer.trace();
mIsVerticalList = false;
return this;
}
/**
* Used privately when performing swipe searches to decide if an element has become
* visible or not.
*
* @param selector
* @return true if found else false
* @since API Level 16
*/
protected boolean exists(UiSelector selector) {
if(getQueryController().findAccessibilityNodeInfo(selector) != null) {
return true;
}
return false;
}
/**
* 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 {@link #getChildByDescription(UiSelector, String, boolean)}
*
* @param childPattern {@link UiSelector} for a child in a scollable layout element
* @param text Content-description to find in the children of
* the <code>childPattern</code> match
* @return {@link UiObject} representing the child element that matches the search conditions
* @throws UiObjectNotFoundException
* @since API Level 16
*/
@Override
public UiObject getChildByDescription(UiSelector childPattern, String text)
throws UiObjectNotFoundException {
Tracer.trace(childPattern, text);
return getChildByDescription(childPattern, text, true);
}
/**
* 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).
*
* @param childPattern {@link UiSelector} for a child in a scollable layout element
* @param text Content-description to find in the children of
* the <code>childPattern</code> match (may be a partial match)
* @param allowScrollSearch set to true if scrolling is allowed
* @return {@link UiObject} representing the child element that matches the search conditions
* @throws UiObjectNotFoundException
* @since API Level 16
*/
public UiObject getChildByDescription(UiSelector childPattern, String text,
boolean allowScrollSearch) throws UiObjectNotFoundException {
Tracer.trace(childPattern, text, allowScrollSearch);
if (text != null) {
if (allowScrollSearch) {
scrollIntoView(new UiSelector().descriptionContains(text));
}
return super.getChildByDescription(childPattern, text);
}
throw new UiObjectNotFoundException("for description= \"" + text + "\"");
}
/**
* 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.
*
* @param childPattern {@link UiSelector} for a child in a scollable layout element
* @param instance int number representing the occurance of
* a <code>childPattern</code> match
* @return {@link UiObject} representing the child element that matches the search conditions
* @since API Level 16
*/
@Override
public UiObject getChildByInstance(UiSelector childPattern, int instance)
throws UiObjectNotFoundException {
Tracer.trace(childPattern, instance);
UiSelector patternSelector = UiSelector.patternBuilder(getSelector(),
UiSelector.patternBuilder(childPattern).instance(instance));
return new UiObject(patternSelector);
}
/**
* 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 {@link #getChildByText(UiSelector, String, boolean)}
*
* @param childPattern {@link UiSelector} selector for a child in a scrollable layout element
* @param text String to find in the children of the <code>childPattern</code> match
* @return {@link UiObject} representing the child element that matches the search conditions
* @throws UiObjectNotFoundException
* @since API Level 16
*/
@Override
public UiObject getChildByText(UiSelector childPattern, String text)
throws UiObjectNotFoundException {
Tracer.trace(childPattern, text);
return getChildByText(childPattern, text, true);
}
/**
* 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).
*
* @param childPattern {@link UiSelector} selector for a child in a scrollable layout element
* @param text String to find in the children of the <code>childPattern</code> match
* @param allowScrollSearch set to true if scrolling is allowed
* @return {@link UiObject} representing the child element that matches the search conditions
* @throws UiObjectNotFoundException
* @since API Level 16
*/
public UiObject getChildByText(UiSelector childPattern, String text, boolean allowScrollSearch)
throws UiObjectNotFoundException {
Tracer.trace(childPattern, text, allowScrollSearch);
if (text != null) {
if (allowScrollSearch) {
scrollIntoView(new UiSelector().text(text));
}
return super.getChildByText(childPattern, text);
}
throw new UiObjectNotFoundException("for text= \"" + 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 {@link #setMaxSearchSwipes(int)}
*
* @param text content-description to find within the contents of this scrollable layout element.
* @return true if item is found; else, false
* @since API Level 16
*/
public boolean scrollDescriptionIntoView(String text) throws UiObjectNotFoundException {
Tracer.trace(text);
return scrollIntoView(new UiSelector().description(text));
}
/**
* Perform a forward scroll action to move through the scrollable layout element until
* a visible item that matches the {@link UiObject} is found.
*
* @param obj {@link UiObject}
* @return true if the item was found and now is in view else false
* @since API Level 16
*/
public boolean scrollIntoView(UiObject obj) throws UiObjectNotFoundException {
Tracer.trace(obj.getSelector());
return scrollIntoView(obj.getSelector());
}
/**
* Perform a scroll forward action to move through the scrollable layout
* element until a visible item that matches the selector is found.
*
* See {@link #scrollDescriptionIntoView(String)} and {@link #scrollTextIntoView(String)}.
*
* @param selector {@link UiSelector} selector
* @return true if the item was found and now is in view; else, false
* @since API Level 16
*/
public boolean scrollIntoView(UiSelector selector) throws UiObjectNotFoundException {
Tracer.trace(selector);
// if we happen to be on top of the text we want then return here
UiSelector childSelector = getSelector().childSelector(selector);
if (exists(childSelector)) {
return (true);
} else {
// we will need to reset the search from the beginning to start search
scrollToBeginning(mMaxSearchSwipes);
if (exists(childSelector)) {
return (true);
}
for (int x = 0; x < mMaxSearchSwipes; x++) {
boolean scrolled = scrollForward();
if(exists(childSelector)) {
return true;
}
if (!scrolled) {
return false;
}
}
}
return false;
}
/**
* Scrolls forward until the UiObject is fully visible in the scrollable container.
* Use this method to make sure that the child item's edges are not offscreen.
*
* @param childObject {@link UiObject} representing the child element
* @return true if the child element is already fully visible, or
* if the method scrolled successfully until the child became fully visible;
* otherwise, false if the attempt to scroll failed.
* @throws UiObjectNotFoundException
* @hide
*/
public boolean ensureFullyVisible(UiObject childObject) throws UiObjectNotFoundException {
Rect actual = childObject.getBounds();
Rect visible = childObject.getVisibleBounds();
if (visible.width() * visible.height() == actual.width() * actual.height()) {
// area match, item fully visible
return true;
}
boolean shouldSwipeForward = false;
if (mIsVerticalList) {
// if list is vertical, matching top edge implies obscured bottom edge
// so we need to scroll list forward
shouldSwipeForward = actual.top == visible.top;
} else {
// if list is horizontal, matching left edge implies obscured right edge,
// so we need to scroll list forward
shouldSwipeForward = actual.left == visible.left;
}
if (mIsVerticalList) {
if (shouldSwipeForward) {
return swipeUp(10);
} else {
return swipeDown(10);
}
} else {
if (shouldSwipeForward) {
return swipeLeft(10);
} else {
return swipeRight(10);
}
}
}
/**
* 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 {@link #setMaxSearchSwipes(int)}
*
* @param text test to look for
* @return true if item is found; else, false
* @since API Level 16
*/
public boolean scrollTextIntoView(String text) throws UiObjectNotFoundException {
Tracer.trace(text);
return scrollIntoView(new UiSelector().text(text));
}
/**
* Sets the maximum number of scrolls allowed when performing a
* scroll action in search of a child element.
* See {@link #getChildByDescription(UiSelector, String)} and
* {@link #getChildByText(UiSelector, String)}.
*
* @param swipes the number of search swipes to perform until giving up
* @return reference to itself
* @since API Level 16
*/
public UiScrollable setMaxSearchSwipes(int swipes) {
Tracer.trace(swipes);
mMaxSearchSwipes = swipes;
return this;
}
/**
* Gets the maximum number of scrolls allowed when performing a
* scroll action in search of a child element.
* See {@link #getChildByDescription(UiSelector, String)} and
* {@link #getChildByText(UiSelector, String)}.
*
* @return max the number of search swipes to perform until giving up
* @since API Level 16
*/
public int getMaxSearchSwipes() {
Tracer.trace();
return mMaxSearchSwipes;
}
/**
* 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.
*
* @return true if scrolled, false if can't scroll anymore
* @since API Level 16
*/
public boolean flingForward() throws UiObjectNotFoundException {
Tracer.trace();
return scrollForward(FLING_STEPS);
}
/**
* 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.
*
* @return true if scrolled, false if can't scroll anymore
* @since API Level 16
*/
public boolean scrollForward() throws UiObjectNotFoundException {
Tracer.trace();
return scrollForward(SCROLL_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.
*
* @param steps number of steps. Use this to control the speed of the scroll action
* @return true if scrolled, false if can't scroll anymore
* @since API Level 16
*/
public boolean scrollForward(int steps) throws UiObjectNotFoundException {
Tracer.trace(steps);
Log.d(LOG_TAG, "scrollForward() on selector = " + getSelector());
AccessibilityNodeInfo node = findAccessibilityNodeInfo(WAIT_FOR_SELECTOR_TIMEOUT);
if(node == null) {
throw new UiObjectNotFoundException(getSelector().toString());
}
Rect rect = new Rect();
node.getBoundsInScreen(rect);
int downX = 0;
int downY = 0;
int upX = 0;
int upY = 0;
// scrolling is by default assumed vertically unless the object is explicitly
// set otherwise by setAsHorizontalContainer()
if(mIsVerticalList) {
int swipeAreaAdjust = (int)(rect.height() * getSwipeDeadZonePercentage());
// scroll vertically: swipe down -> up
downX = rect.centerX();
downY = rect.bottom - swipeAreaAdjust;
upX = rect.centerX();
upY = rect.top + swipeAreaAdjust;
} else {
int swipeAreaAdjust = (int)(rect.width() * getSwipeDeadZonePercentage());
// scroll horizontally: swipe right -> left
// TODO: Assuming device is not in right to left language
downX = rect.right - swipeAreaAdjust;
downY = rect.centerY();
upX = rect.left + swipeAreaAdjust;
upY = rect.centerY();
}
return getInteractionController().scrollSwipe(downX, downY, upX, upY, steps);
}
/**
* 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.
*
* @return true if scrolled, and false if can't scroll anymore
* @since API Level 16
*/
public boolean flingBackward() throws UiObjectNotFoundException {
Tracer.trace();
return scrollBackward(FLING_STEPS);
}
/**
* 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.
*
* @return true if scrolled, and false if can't scroll anymore
* @since API Level 16
*/
public boolean scrollBackward() throws UiObjectNotFoundException {
Tracer.trace();
return scrollBackward(SCROLL_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.
*
* @param steps number of steps. Use this to control the speed of the scroll action.
* @return true if scrolled, false if can't scroll anymore
* @since API Level 16
*/
public boolean scrollBackward(int steps) throws UiObjectNotFoundException {
Tracer.trace(steps);
Log.d(LOG_TAG, "scrollBackward() on selector = " + getSelector());
AccessibilityNodeInfo node = findAccessibilityNodeInfo(WAIT_FOR_SELECTOR_TIMEOUT);
if (node == null) {
throw new UiObjectNotFoundException(getSelector().toString());
}
Rect rect = new Rect();
node.getBoundsInScreen(rect);
int downX = 0;
int downY = 0;
int upX = 0;
int upY = 0;
// scrolling is by default assumed vertically unless the object is explicitly
// set otherwise by setAsHorizontalContainer()
if(mIsVerticalList) {
int swipeAreaAdjust = (int)(rect.height() * getSwipeDeadZonePercentage());
Log.d(LOG_TAG, "scrollToBegining() using vertical scroll");
// scroll vertically: swipe up -> down
downX = rect.centerX();
downY = rect.top + swipeAreaAdjust;
upX = rect.centerX();
upY = rect.bottom - swipeAreaAdjust;
} else {
int swipeAreaAdjust = (int)(rect.width() * getSwipeDeadZonePercentage());
Log.d(LOG_TAG, "scrollToBegining() using hotizontal scroll");
// scroll horizontally: swipe left -> right
// TODO: Assuming device is not in right to left language
downX = rect.left + swipeAreaAdjust;
downY = rect.centerY();
upX = rect.right - swipeAreaAdjust;
upY = rect.centerY();
}
return getInteractionController().scrollSwipe(downX, downY, upX, upY, 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.
*
* @param steps use steps to control the speed, so that it may be a scroll, or fling
* @return true on scrolled else false
* @since API Level 16
*/
public boolean scrollToBeginning(int maxSwipes, int steps) throws UiObjectNotFoundException {
Tracer.trace(maxSwipes, steps);
Log.d(LOG_TAG, "scrollToBeginning() on selector = " + getSelector());
// protect against potential hanging and return after preset attempts
for(int x = 0; x < maxSwipes; x++) {
if(!scrollBackward(steps)) {
break;
}
}
return true;
}
/**
* 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.
*
* @param maxSwipes
* @return true on scrolled else false
* @since API Level 16
*/
public boolean scrollToBeginning(int maxSwipes) throws UiObjectNotFoundException {
Tracer.trace(maxSwipes);
return scrollToBeginning(maxSwipes, SCROLL_STEPS);
}
/**
* 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.
*
* @param maxSwipes
* @return true on scrolled else false
* @since API Level 16
*/
public boolean flingToBeginning(int maxSwipes) throws UiObjectNotFoundException {
Tracer.trace(maxSwipes);
return scrollToBeginning(maxSwipes, FLING_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.
*
* @param steps use steps to control the speed, so that it may be a scroll, or fling
* @return true on scrolled else false
* @since API Level 16
*/
public boolean scrollToEnd(int maxSwipes, int steps) throws UiObjectNotFoundException {
Tracer.trace(maxSwipes, steps);
// protect against potential hanging and return after preset attempts
for(int x = 0; x < maxSwipes; x++) {
if(!scrollForward(steps)) {
break;
}
}
return true;
}
/**
* 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.
*
* @param maxSwipes
* @return true on scrolled, else false
* @since API Level 16
*/
public boolean scrollToEnd(int maxSwipes) throws UiObjectNotFoundException {
Tracer.trace(maxSwipes);
return scrollToEnd(maxSwipes, SCROLL_STEPS);
}
/**
* 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.
*
* @param maxSwipes
* @return true on scrolled, else false
* @since API Level 16
*/
public boolean flingToEnd(int maxSwipes) throws UiObjectNotFoundException {
Tracer.trace(maxSwipes);
return scrollToEnd(maxSwipes, FLING_STEPS);
}
/**
* 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.
*
* @return a value between 0 and 1
* @since API Level 16
*/
public double getSwipeDeadZonePercentage() {
Tracer.trace();
return mSwipeDeadZonePercentage;
}
/**
* 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.
*
* @param swipeDeadZonePercentage is a value between 0 and 1
* @return reference to itself
* @since API Level 16
*/
public UiScrollable setSwipeDeadZonePercentage(double swipeDeadZonePercentage) {
Tracer.trace(swipeDeadZonePercentage);
mSwipeDeadZonePercentage = swipeDeadZonePercentage;
return this;
}
}