diff options
author | quddusc <quddusc@google.com> | 2013-06-13 13:57:32 -0700 |
---|---|---|
committer | quddusc <quddusc@google.com> | 2013-06-17 11:32:38 -0700 |
commit | 753092685410ea01dbb122162cd40cac48332ae1 (patch) | |
tree | 7f0d8b2d2b314dc2fdd991950e9b9bbe66151507 /library/core-src/com/android/uiautomator | |
parent | 32fcb04ad8fce5d077f1e0ea66210397dcd98818 (diff) | |
download | uiautomator-753092685410ea01dbb122162cd40cac48332ae1.tar.gz |
docs: Edited Javadoc comments in uiautomator library source files (MR2).
Change-Id: I3eff0160ecb4769f2a7b26af68794f761dbd5cbc
Diffstat (limited to 'library/core-src/com/android/uiautomator')
5 files changed, 418 insertions, 349 deletions
diff --git a/library/core-src/com/android/uiautomator/core/Configurator.java b/library/core-src/com/android/uiautomator/core/Configurator.java index 55ed3e7..5f62fc3 100644 --- a/library/core-src/com/android/uiautomator/core/Configurator.java +++ b/library/core-src/com/android/uiautomator/core/Configurator.java @@ -16,10 +16,14 @@ package com.android.uiautomator.core; /** - * The Configurator allows for modification of some key framework parameters. - * New settings take effect immediately and can be changed any time during a test run. + * Allows you to set key parameters for running uiautomator tests. The new + * settings take effect immediately and can be changed any time during a test run. * - * Can be obtained by calling {@link #getInstance()} + * To modify parameters using Configurator, first obtain an instance by calling + * {@link #getInstance()}. As a best practice, make sure you always save + * the original value of any parameter that you are modifying. After running your + * tests with the modified parameters, make sure to also restore + * the original parameter values, otherwise this will impact other tests cases. * @since API Level 18 */ public final class Configurator { @@ -42,7 +46,7 @@ public final class Configurator { } /** - * Retrieves a singleton instance of Configurator + * Retrieves a singleton instance of Configurator. * * @return Configurator instance * @since API Level 18 @@ -55,11 +59,15 @@ public final class Configurator { } /** - * Sets the timeout used to wait for user interface idle before an automation action. + * Sets the timeout for waiting for the user interface to go into an idle + * state before starting a uiautomator action. * - * All automation APIs, except {@link UiDevice}, perform this wait for idle before looking for - * the widget specified by the object's {@link UiSelector}. Once idle is detected, a - * wait for selector will begin. See {@link #setWaitForSelectorTimeout(long)} + * By default, all core uiautomator objects except {@link UiDevice} will perform + * this wait before starting to search for the widget specified by the + * object's {@link UiSelector}. Once the idle state is detected or the + * timeout elapses (whichever occurs first), the object will start to wait + * for the selector to find a match. + * See {@link #setWaitForSelectorTimeout(long)} * * @param timeout Timeout value in milliseconds * @return self @@ -71,13 +79,17 @@ public final class Configurator { } /** - * Gets the timeout used to wait for user interface idle before an automation action. + * Gets the current timeout used for waiting for the user interface to go + * into an idle state. * - * All automation APIs, except {@link UiDevice}, perform this wait for idle before looking for - * the widget specified by the object's {@link UiSelector}. Once idle is detected, a - * wait for selector will begin. See {@link #setWaitForSelectorTimeout(long)} + * By default, all core uiautomator objects except {@link UiDevice} will perform + * this wait before starting to search for the widget specified by the + * object's {@link UiSelector}. Once the idle state is detected or the + * timeout elapses (whichever occurs first), the object will start to wait + * for the selector to find a match. + * See {@link #setWaitForSelectorTimeout(long)} * - * @return current timeout in milliseconds + * @return Current timeout value in milliseconds * @since API Level 18 */ public long getWaitForIdleTimeout() { @@ -85,12 +97,13 @@ public final class Configurator { } /** - * Sets the timeout used to wait for a widget matching a selector to become visible - * in user interface. + * Sets the timeout for waiting for a widget to become visible in the user + * interface so that it can be matched by a selector. * - * The user interface content is dynamic and sometimes the specific widget to be - * automated may not yet be visible. This wait allows the framework to keep looking - * for a matching widget to the object's {@link UiSelector}, up until the timeout. + * Because user interface content is dynamic, sometimes a widget may not + * be visible immediately and won't be detected by a selector. This timeout + * allows the uiautomator framework to wait for a match to be found, up until + * the timeout elapses. * * @param timeout Timeout value in milliseconds. * @return self @@ -102,14 +115,15 @@ public final class Configurator { } /** - * Gets the timeout used to wait for a widget matching a selector to become visible - * in user interface. + * Gets the current timeout for waiting for a widget to become visible in + * the user interface so that it can be matched by a selector. * - * The user interface content is dynamic and sometimes the specific widget to be - * automated, may not yet be visible. This wait allows the framework to keep looking - * for a matching widget to the object's {@link UiSelector}, up until the timeout. + * Because user interface content is dynamic, sometimes a widget may not + * be visible immediately and won't be detected by a selector. This timeout + * allows the uiautomator framework to wait for a match to be found, up until + * the timeout elapses. * - * @return current timeout in milliseconds + * @return Current timeout value in milliseconds * @since API Level 18 */ public long getWaitForSelectorTimeout() { @@ -117,13 +131,13 @@ public final class Configurator { } /** - * Sets the timeout used to wait for acknowledgment events caused by automation scroll - * swipe action. + * Sets the timeout for waiting for an acknowledgement of an + * uiautomtor scroll swipe action. * - * The acknowledgment event is an accessibility event, corresponding to the scroll action. - * This acknowledgment helps the framework determine if the requested action was successful. - * Changing this timeout value should only be made in very rare cases and in general use, - * should not be modified. + * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>, + * corresponding to the scroll action, that lets the framework determine if + * the scroll action was successful. Generally, this timeout should not be modified. + * See {@link UiScrollable} * * @param timeout Timeout value in milliseconds * @return self @@ -135,13 +149,13 @@ public final class Configurator { } /** - * Gets the timeout used to wait for acknowledgment events caused by automation scroll - * swipe action. + * Gets the timeout for waiting for an acknowledgement of an + * uiautomtor scroll swipe action. * - * The acknowledgment event is an accessibility event, corresponding to the scroll action. - * This acknowledgment helps the framework determine if the requested action was successful. - * Changing this timeout value should only be made in very rare cases and in general use, - * should not be modified. + * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>, + * corresponding to the scroll action, that lets the framework determine if + * the scroll action was successful. Generally, this timeout should not be modified. + * See {@link UiScrollable} * * @return current timeout in milliseconds * @since API Level 18 @@ -151,13 +165,13 @@ public final class Configurator { } /** - * Sets the timeout used to wait for acknowledgment events caused by generic automation - * actions such as clicks, setText, pressMenu etc... + * Sets the timeout for waiting for an acknowledgment of generic uiautomator + * actions, such as clicks, text setting, and menu presses. * - * The acknowledgment event is an accessibility event, corresponding to an action, that the - * framework looks for after an action is performed. This acknowledgment helps the - * framework determine if the requested action was successful. Changing this timeout - * value should only be made in very rare cases and in general use, should not be modified. + * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>, + * corresponding to an action, that lets the framework determine if the + * action was successful. Generally, this timeout should not be modified. + * See {@link UiObject} * * @param timeout Timeout value in milliseconds * @return self @@ -169,13 +183,13 @@ public final class Configurator { } /** - * Gets the timeout used to wait for acknowledgment events caused by generic automation - * actions such as clicks, setText, pressMenu etc... + * Gets the current timeout for waiting for an acknowledgment of generic + * uiautomator actions, such as clicks, text setting, and menu presses. * - * The acknowledgment event is an accessibility event, corresponding to an action, that the - * framework looks for after an action is performed. This acknowledgment helps the - * framework determine if the requested action was successful. Changing this timeout - * value should only be made in very rare cases and in general use, should not be modified. + * The acknowledgment is an <a href="http://developer.android.com/reference/android/view/accessibility/AccessibilityEvent.html">AccessibilityEvent</a>, + * corresponding to an action, that lets the framework determine if the + * action was successful. Generally, this timeout should not be modified. + * See {@link UiObject} * * @return current timeout in milliseconds * @since API Level 18 @@ -185,7 +199,8 @@ public final class Configurator { } /** - * Sets a delay between key presses when sending text. + * Sets a delay between key presses when injecting text input. + * See {@link UiObject#setText(String)} * * @param delay Delay value in milliseconds * @return self @@ -197,7 +212,8 @@ public final class Configurator { } /** - * Gets the delay between key presses when sending text. + * Gets the current delay between key presses when injecting text input. + * See {@link UiObject#setText(String)} * * @return current delay in milliseconds * @since API Level 18 @@ -205,4 +221,4 @@ public final class Configurator { public long getKeyInjectionDelay() { return mKeyInjectionDelay; } -} + diff --git a/library/core-src/com/android/uiautomator/core/UiDevice.java b/library/core-src/com/android/uiautomator/core/UiDevice.java index 5a2f3a7..8737685 100644 --- a/library/core-src/com/android/uiautomator/core/UiDevice.java +++ b/library/core-src/com/android/uiautomator/core/UiDevice.java @@ -87,13 +87,14 @@ public class UiDevice { } /** - * Enabled or disabled the compressed layout hierarchy + * Enables or disables layout hierarchy compression. * - * Enabling the compressed layout hierarchy, limits the layout hierarchy returned - * by accessibility, only to the important nodes to automation, removing unnecessary - * surrounding layout nodes that make viewing and searching the hierarchy inefficient. + * If compression is enabled, the layout hierarchy derived from the Acessibility + * framework will only contain nodes that are important for uiautomator + * testing. Any unnecessary surrounding layout nodes that make viewing + * and searching the hierarchy inefficient are removed. * - * @param compressed is true to enabled else false to disable + * @param compressed true to enable compression; else, false to disable * @since API Level 18 */ public void setCompressedLayoutHeirarchy(boolean compressed) { @@ -340,7 +341,7 @@ public class UiDevice { } /** - * Opens the notification shade + * Opens the notification shade. * * @return true if successful, else return false * @since API Level 18 @@ -352,7 +353,7 @@ public class UiDevice { } /** - * Opens the quick settings shade + * Opens the Quick Settings shade. * * @return true if successful, else return false * @since API Level 18 @@ -427,16 +428,18 @@ public class UiDevice { } /** - * Performs a swipe from one coordinate to another using the number of steps - * to determine smoothness and speed. Each step execution is throttled to 5ms - * per step. So for a 100 steps, the swipe will take about 1/2 second to complete. + * Performs a swipe from one coordinate to another coordinate. You can control + * the smoothness and speed of the swipe by specifying the number of steps. + * Each step execution is throttled to 5 milliseconds per step, so for a 100 + * steps, the swipe will take around 0.5 seconds to complete. * - * @param startX - * @param startY - * @param endX - * @param endY - * @param steps is the number of move steps sent to the system - * @return false if the operation fails or the coordinates are invalid + * @param startX X-axis value for the starting coordinate + * @param startY Y-axis value for the starting coordinate + * @param endX X-axis value for the ending coordinate + * @param endY Y-axis value for the ending coordinate + * @param steps is the number of steps for the swipe action + * @return true if swipe is performed, false if the operation fails + * or the coordinates are invalid * @since API Level 18 */ public boolean drag(int startX, int startY, int endX, int endY, int steps) { @@ -842,4 +845,4 @@ public class UiDevice { Tracer.trace(storePath, scale, quality); return mUiAutomationBridge.takeScreenshot(storePath, quality); } -} + diff --git a/library/core-src/com/android/uiautomator/core/UiObject.java b/library/core-src/com/android/uiautomator/core/UiObject.java index 9fdfae5..c92864f 100644 --- a/library/core-src/com/android/uiautomator/core/UiObject.java +++ b/library/core-src/com/android/uiautomator/core/UiObject.java @@ -25,11 +25,11 @@ import android.view.MotionEvent.PointerCoords; import android.view.accessibility.AccessibilityNodeInfo; /** - * A UiObject is a representation of a UI element. It is not in any way directly bound to a - * UI element as an object reference. A UiObject holds information to help it - * locate a matching UI element at runtime based on the {@link UiSelector} properties specified in - * its constructor. Since a UiObject is a representative for a UI element, it can - * be reused for different views with matching UI elements. + * A UiObject is a representation of a view. It is not in any way directly bound to a + * view as an object reference. A UiObject contains information to help it + * locate a matching view at runtime based on the {@link UiSelector} properties specified in + * its constructor. Once you create an instance of a UiObject, it can + * be reused for different views that match the selector criteria. * @since API Level 16 */ public class UiObject { @@ -70,8 +70,8 @@ public class UiObject { private final Configurator mConfig = Configurator.getInstance(); /** - * Constructs a UiObject to represent a specific UI element matched by the specified - * {@link UiSelector} selector properties. + * Constructs a UiObject to represent a view that matches the specified + * selector criteria. * @param selector * @since API Level 16 */ @@ -104,7 +104,7 @@ public class UiObject { /** * Retrieves the {@link InteractionController} to perform finger actions such as tapping, - * swiping or entering text. + * swiping, or entering text. * * @return {@link InteractionController} */ @@ -113,11 +113,10 @@ public class UiObject { } /** - * Creates a new UiObject representing a child UI element of the element currently represented - * by this UiObject. + * Creates a new UiObject for a child view that is under the present UiObject. * - * @param selector for UI element to match - * @return a new UiObject representing the matched UI element + * @param selector for child view to match + * @return a new UiObject representing the child view * @since API Level 16 */ public UiObject getChild(UiSelector selector) throws UiObjectNotFoundException { @@ -126,13 +125,11 @@ public class UiObject { } /** - * Creates a new UiObject representing a child UI element from the parent element currently - * represented by this object. Essentially this is starting the search from the parent - * element and can also be used to find sibling UI elements to the one currently represented - * by this UiObject. + * Creates a new UiObject for a sibling view or a child of the sibling view, + * relative to the present UiObject. * - * @param selector for the UI element to match - * @return a new UiObject representing the matched UI element + * @param selector for a sibling view or children of the sibling view + * @return a new UiObject representing the matched view * @throws UiObjectNotFoundException * @since API Level 16 */ @@ -142,10 +139,9 @@ public class UiObject { } /** - * Counts the child UI elements immediately under the UI element currently represented by - * this UiObject. + * Counts the child views immediately under the present UiObject. * - * @return the count of child UI elements. + * @return the count of child views. * @throws UiObjectNotFoundException * @since API Level 16 */ @@ -159,8 +155,8 @@ public class UiObject { } /** - * Uses the member UiSelector properties to find a matching UI element reported in - * the accessibility hierarchy. + * Finds a matching UI element in the accessibility hierarchy, by + * using the selector for this UiObject. * * @param timeout in milliseconds * @return AccessibilityNodeInfo if found else null @@ -187,13 +183,14 @@ public class UiObject { } /** - * Performs a drag of this object to a destination UiObject. Note that the number of steps - * used can influence the drag speed and varying speeds may impact the results. Consider - * evaluating different speeds when testing this method. + * Drags this object to a destination UiObject. + * The number of steps specified in your input parameter can influence the + * drag speed, and varying speeds may impact the results. Consider + * evaluating different speeds when using this method in your tests. * - * @param destObj - * @param steps usually 40 steps. More or less to change the speed. - * @return true of successful + * @param destObj the destination UiObject. + * @param steps usually 40 steps. You can increase or decrease the steps to change the speed. + * @return true if successful * @throws UiObjectNotFoundException * @since API Level 18 */ @@ -205,14 +202,15 @@ public class UiObject { } /** - * Performs a drag of this object to arbitrary coordinates. Note that the number of steps - * used will influence the drag speed and varying speeds may impact the results. Consider - * evaluating different speeds when testing this method. + * Drags this object to arbitrary coordinates. + * The number of steps specified in your input parameter can influence the + * drag speed, and varying speeds may impact the results. Consider + * evaluating different speeds when using this method in your tests. * - * @param destX - * @param destY - * @param steps - * @return true of successful + * @param destX the X-axis coordinate. + * @param destY the Y-axis coordinate. + * @param steps usually 40 steps. You can increase or decrease the steps to change the speed. + * @return true if successful * @throws UiObjectNotFoundException * @since API Level 18 */ @@ -223,9 +221,14 @@ public class UiObject { } /** - * Perform the action on the UI element that is represented by this UiObject. Also see - * {@link UiScrollable#scrollToBeginning(int)}, {@link UiScrollable#scrollToEnd(int)}, - * {@link UiScrollable#scrollBackward()}, {@link UiScrollable#scrollForward()}. + * Performs the swipe up action on the UiObject. + * See also: + * <ul> + * <li>{@link UiScrollable#scrollToBeginning(int)}</li> + * <li>{@link UiScrollable#scrollToEnd(int)}</li> + * <li>{@link UiScrollable#scrollBackward()}</li> + * <li>{@link UiScrollable#scrollForward()}</li> + * </ul> * * @param steps indicates the number of injected move steps into the system. Steps are * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete. @@ -244,12 +247,16 @@ public class UiObject { } /** - * Perform the action on the UI element that is represented by this object, Also see - * {@link UiScrollable#scrollToBeginning(int)}, {@link UiScrollable#scrollToEnd(int)}, - * {@link UiScrollable#scrollBackward()}, {@link UiScrollable#scrollForward()}. This method will - * perform the swipe gesture over any surface. The targeted UI element does not need to have - * the attribute <code>scrollable</code> set to <code>true</code> for this operation to be - * performed. + * Performs the swipe down action on the UiObject. + * The swipe gesture can be performed over any surface. The targeted + * UI element does not need to be scrollable. + * See also: + * <ul> + * <li>{@link UiScrollable#scrollToBeginning(int)}</li> + * <li>{@link UiScrollable#scrollToEnd(int)}</li> + * <li>{@link UiScrollable#scrollBackward()}</li> + * <li>{@link UiScrollable#scrollForward()}</li> + * </ul> * * @param steps indicates the number of injected move steps into the system. Steps are * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete. @@ -268,12 +275,16 @@ public class UiObject { } /** - * Perform the action on the UI element that is represented by this object. Also see - * {@link UiScrollable#scrollToBeginning(int)}, {@link UiScrollable#scrollToEnd(int)}, - * {@link UiScrollable#scrollBackward()}, {@link UiScrollable#scrollForward()}. This method will - * perform the swipe gesture over any surface. The targeted UI element does not need to have the - * attribute <code>scrollable</code> set to <code>true</code> for this operation to be - * performed. + * Performs the swipe left action on the UiObject. + * The swipe gesture can be performed over any surface. The targeted + * UI element does not need to be scrollable. + * See also: + * <ul> + * <li>{@link UiScrollable#scrollToBeginning(int)}</li> + * <li>{@link UiScrollable#scrollToEnd(int)}</li> + * <li>{@link UiScrollable#scrollBackward()}</li> + * <li>{@link UiScrollable#scrollForward()}</li> + * </ul> * * @param steps indicates the number of injected move steps into the system. Steps are * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete. @@ -291,12 +302,16 @@ public class UiObject { } /** - * Perform the action on the UI element that is represented by this object. Also see - * {@link UiScrollable#scrollToBeginning(int)}, {@link UiScrollable#scrollToEnd(int)}, - * {@link UiScrollable#scrollBackward()}, {@link UiScrollable#scrollForward()}. This method will - * perform the swipe gesture over any surface. The targeted UI element does not need to have the - * attribute <code>scrollable</code> set to <code>true</code> for this operation to be - * performed. + * Performs the swipe right action on the UiObject. + * The swipe gesture can be performed over any surface. The targeted + * UI element does not need to be scrollable. + * See also: + * <ul> + * <li>{@link UiScrollable#scrollToBeginning(int)}</li> + * <li>{@link UiScrollable#scrollToEnd(int)}</li> + * <li>{@link UiScrollable#scrollBackward()}</li> + * <li>{@link UiScrollable#scrollForward()}</li> + * </ul> * * @param steps indicates the number of injected move steps into the system. Steps are * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete. @@ -345,10 +360,10 @@ public class UiObject { } /** - * Walk the hierarchy up to find a scrollable parent. A scrollable parent - * indicates that this node may be in a content where it is partially - * visible due to scrolling. its clickable center maybe invisible and - * adjustments should be made to the click coordinates. + * Walks up the layout hierarchy to find a scrollable parent. A scrollable parent + * indicates that this node might be in a container where it is partially + * visible due to scrolling. In this case, its clickable center might not be visible and + * the click coordinates should be adjusted. * * @param node * @return The accessibility node info. @@ -384,9 +399,9 @@ public class UiObject { } /** + * Waits for window transitions that would typically take longer than the + * usual default timeouts. * See {@link #clickAndWaitForNewWindow(long)} - * This method is intended to reliably wait for window transitions that would typically take - * longer than the usual default timeouts. * * @return true if the event was triggered, else false * @throws UiObjectNotFoundException @@ -527,10 +542,10 @@ public class UiObject { } /** - * Reads the <code>className</code> property of the UI element + * Retrieves the <code>className</code> property of the UI element. * * @return class name of the current node represented by this UiObject - * @throws UiObjectNotFoundException if no match could be found + * @throws UiObjectNotFoundException if no match was found * @since API Level 18 */ public String getClassName() throws UiObjectNotFoundException { @@ -637,7 +652,7 @@ public class UiObject { } /** - * Check if the UI element's <code>selected</code> property is currently true + * Checks if the UI element's <code>selected</code> property is currently true. * * @return true if it is else false * @throws UiObjectNotFoundException @@ -653,7 +668,7 @@ public class UiObject { } /** - * Check if the UI element's <code>checkable</code> property is currently true + * Checks if the UI element's <code>checkable</code> property is currently true. * * @return true if it is else false * @throws UiObjectNotFoundException @@ -669,7 +684,7 @@ public class UiObject { } /** - * Check if the UI element's <code>enabled</code> property is currently true + * Checks if the UI element's <code>enabled</code> property is currently true. * * @return true if it is else false * @throws UiObjectNotFoundException @@ -685,7 +700,7 @@ public class UiObject { } /** - * Check if the UI element's <code>clickable</code> property is currently true + * Checks if the UI element's <code>clickable</code> property is currently true. * * @return true if it is else false * @throws UiObjectNotFoundException @@ -717,7 +732,7 @@ public class UiObject { } /** - * Check if the UI element's <code>focusable</code> property is currently true + * Check if the UI element's <code>focusable</code> property is currently true. * * @return true if it is else false * @throws UiObjectNotFoundException @@ -733,7 +748,7 @@ public class UiObject { } /** - * Check if the UI element's <code>scrollable</code> property is currently true + * Check if the view's <code>scrollable</code> property is currently true * * @return true if it is else false * @throws UiObjectNotFoundException @@ -749,7 +764,7 @@ public class UiObject { } /** - * Check if the UI element's <code>long-clickable</code> property is currently true + * Check if the view's <code>long-clickable</code> property is currently true * * @return true if it is else false * @throws UiObjectNotFoundException @@ -765,7 +780,7 @@ public class UiObject { } /** - * Reads the UI element's <code>package</code> property + * Reads the view's <code>package</code> property * * @return true if it is else false * @throws UiObjectNotFoundException @@ -781,9 +796,9 @@ public class UiObject { } /** - * Returns the visible bounds of the UI element. + * Returns the visible bounds of the view. * - * If a portion of the UI element is visible, only the bounds of the visible portion are + * If a portion of the view is visible, only the bounds of the visible portion are * reported. * * @return Rect @@ -801,7 +816,7 @@ public class UiObject { } /** - * Returns the UI element's <code>bounds</code> property. See {@link #getVisibleBounds()} + * Returns the view's <code>bounds</code> property. See {@link #getVisibleBounds()} * * @return Rect * @throws UiObjectNotFoundException @@ -820,14 +835,14 @@ public class UiObject { } /** - * Waits a specified length of time for a UI element to become visible. + * Waits a specified length of time for a view to become visible. * - * This method waits until the UI element becomes visible on the display, or + * This method waits until the view becomes visible on the display, or * until the timeout has elapsed. You can use this method in situations where * the content that you want to select is not immediately displayed. * * @param timeout the amount of time to wait (in milliseconds) - * @return true if the UI element is displayed, else false if timeout elapsed while waiting + * @return true if the view is displayed, else false if timeout elapsed while waiting * @since API Level 16 */ public boolean waitForExists(long timeout) { @@ -839,12 +854,12 @@ public class UiObject { } /** - * Waits a specified length of time for a UI element to become undetectable. + * Waits a specified length of time for a view to become undetectable. * - * This method waits until a UI element is no longer matchable, or until the + * This method waits until a view is no longer matchable, or until the * timeout has elapsed. * - * A UI element becomes undetectable when the {@link UiSelector} of the object is + * A view becomes undetectable when the {@link UiSelector} of the object is * unable to find a match because the element has either changed its state or is no * longer displayed. * @@ -871,14 +886,14 @@ public class UiObject { } /** - * Check if UI element exists. + * Check if view exists. * * This methods performs a {@link #waitForExists(long)} with zero timeout. This - * basically returns immediately whether the UI element represented by this UiObject - * exists or not. If you need to wait longer for this UI element, then see + * basically returns immediately whether the view represented by this UiObject + * exists or not. If you need to wait longer for this view, then see * {@link #waitForExists(long)}. * - * @return true if the UI element represented by this UiObject does exist + * @return true if the view represented by this UiObject does exist * @since API Level 16 */ public boolean exists() { @@ -893,14 +908,14 @@ public class UiObject { } /** - * PinchOut generates a 2 pointer gesture where each pointer is moving from the center out - * away from each other diagonally towards the edges of the current UI element represented by + * 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. - * @param percent of the object's diagonal length to use for the pinch - * @param steps indicates the number of injected move steps into the system. Steps are - * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete. + * @param percent percentage of the object's diagonal length for the pinch gesture + * @param steps the number of steps for the gesture. Steps are injected + * about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete. * @return <code>true</code> if all touch events for this gesture are injected successfully, - * <code>false</code> otherwise + * <code>false</code> otherwise * @throws UiObjectNotFoundException * @since API Level 18 */ @@ -932,14 +947,13 @@ public class UiObject { } /** - * PinchIn generates a 2 pointer gesture where each pointer is moving towards the other - * diagonally from the edges of the current UI element represented by this UiObject, until the - * center. - * @param percent of the object's diagonal length to use for the pinch - * @param steps indicates the number of injected move steps into the system. Steps are - * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete. + * Performs a two-pointer gesture, where each pointer moves diagonally + * toward the other, from the edges to the center of this UiObject . + * @param percent percentage of the object's diagonal length for the pinch gesture + * @param steps the number of steps for the gesture. Steps are injected + * about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete. * @return <code>true</code> if all touch events for this gesture are injected successfully, - * <code>false</code> otherwise + * <code>false</code> otherwise * @throws UiObjectNotFoundException * @since API Level 18 */ @@ -969,16 +983,16 @@ public class UiObject { } /** - * Generates a 2 pointer gesture from an arbitrary starting and ending points. + * Generates a two-pointer gesture with arbitrary starting and ending points. * * @param startPoint1 start point of pointer 1 * @param startPoint2 start point of pointer 2 * @param endPoint1 end point of pointer 1 * @param endPoint2 end point of pointer 2 - * @param steps indicates the number of injected move steps into the system. Steps are - * injected about 5ms apart. So a 100 steps may take about 1/2 second to complete. + * @param steps the number of steps for the gesture. Steps are injected + * about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete. * @return <code>true</code> if all touch events for this gesture are injected successfully, - * <code>false</code> otherwise + * <code>false</code> otherwise * @since API Level 18 */ public boolean performTwoPointerGesture(Point startPoint1, Point startPoint2, Point endPoint1, @@ -1044,15 +1058,13 @@ public class UiObject { } /** - * Performs a multi-touch gesture + * Performs a multi-touch gesture. You must specify touch coordinates for + * at least 2 pointers. Each pointer must have all of its touch steps + * defined in an array of {@link PointerCoords}. You can use this method to + * specify complex gestures, like circles and irregular shapes, where each + * pointer may take a different path. * - * Takes a series of touch coordinates for at least 2 pointers. Each pointer must have - * all of its touch steps defined in an array of {@link PointerCoords}. By having the ability - * to specify the touch points along the path of a pointer, the caller is able to specify - * complex gestures like circles, irregular shapes etc, where each pointer may take a - * different path. - * - * To create a single point on a pointer's touch path + * To create a single point on a pointer's touch path: * <code> * PointerCoords p = new PointerCoords(); * p.x = stepX; @@ -1060,14 +1072,14 @@ public class UiObject { * p.pressure = 1; * p.size = 1; * </code> - * @param touches each array of {@link PointerCoords} constitute a single pointer's touch path. - * Multiple {@link PointerCoords} arrays constitute multiple pointers, each with its own - * path. Each {@link PointerCoords} in an array constitute a point on a pointer's path. + * @param touches represents the pointers' paths. Each {@link PointerCoords} + * array represents a different pointer. Each {@link PointerCoords} in an + * array element represents a touch point on a pointer's path. * @return <code>true</code> if all touch events for this gesture are injected successfully, - * <code>false</code> otherwise + * <code>false</code> otherwise * @since API Level 18 */ public boolean performMultiPointerGesture(PointerCoords[] ...touches) { return getInteractionController().performMultiPointerGesture(touches); } -} + diff --git a/library/core-src/com/android/uiautomator/core/UiScrollable.java b/library/core-src/com/android/uiautomator/core/UiScrollable.java index f5306af..9b14c10 100644 --- a/library/core-src/com/android/uiautomator/core/UiScrollable.java +++ b/library/core-src/com/android/uiautomator/core/UiScrollable.java @@ -20,8 +20,9 @@ import android.util.Log; import android.view.accessibility.AccessibilityNodeInfo; /** - * UiScrollable is a {@link UiCollection} and provides support for searching for items in a - * scrollable UI elements. Used with horizontally or vertically scrollable UI. + * 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 { @@ -44,11 +45,10 @@ public class UiScrollable extends UiCollection { private double mSwipeDeadZonePercentage = DEFAULT_SWIPE_DEADZONE_PCT; /** - * UiScrollable is a {@link UiCollection} and as such requires a {@link 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. + * Constructor. * - * @param container a {@link UiSelector} selector + * @param container a {@link UiSelector} selector to identify the scrollable + * layout element. * @since API Level 16 */ public UiScrollable(UiSelector container) { @@ -58,7 +58,7 @@ public class UiScrollable extends UiCollection { } /** - * Set the direction of swipes when performing scroll search + * Set the direction of swipes to be vertical when performing scroll actions. * @return reference to itself * @since API Level 16 */ @@ -69,7 +69,7 @@ public class UiScrollable extends UiCollection { } /** - * Set the direction of swipes when performing scroll search + * Set the direction of swipes to be horizontal when performing scroll actions. * @return reference to itself * @since API Level 16 */ @@ -95,17 +95,19 @@ public class UiScrollable extends UiCollection { } /** - * Searches for child UI element within the constraints of this UiScrollable {@link UiSelector} - * container. It looks for any child matching the <code>childPattern</code> argument within its - * hierarchy with a matching content-description text. The returned UiObject will represent the - * UI element matching the <code>childPattern</code> and not the sub element that matched the - * content description.</p> - * By default this operation will perform scroll search while attempting to find the UI element + * 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} selector of the child pattern to match and return - * @param text String of the identifying child contents of of the <code>childPattern</code> - * @return {@link UiObject} pointing at and instance of <code>childPattern</code> + * @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 */ @@ -117,12 +119,18 @@ public class UiScrollable extends UiCollection { } /** - * See {@link #getChildByDescription(UiSelector, String)} - * - * @param childPattern {@link UiSelector} selector of the child pattern to match and return - * @param text String may be a partial match for the content-description of a child element. + * 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} pointing at and instance of <code>childPattern</code> + * @return {@link UiObject} representing the child element that matches the search conditions * @throws UiObjectNotFoundException * @since API Level 16 */ @@ -139,14 +147,14 @@ public class UiScrollable extends UiCollection { } /** - * Searches for child UI element within the constraints of this UiScrollable {@link UiSelector} - * selector. It looks for any child matching the <code>childPattern</code> argument and - * return the <code>instance</code> specified. The operation is performed only on the visible - * items and no scrolling is performed in this case. - * - * @param childPattern {@link UiSelector} selector of the child pattern to match and return - * @param instance int the desired matched instance of this <code>childPattern</code> - * @return {@link UiObject} pointing at and instance of <code>childPattern</code> + * 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 @@ -159,18 +167,18 @@ public class UiScrollable extends UiCollection { } /** - * Searches for child UI element within the constraints of this UiScrollable {@link UiSelector} - * container. It looks for any child matching the <code>childPattern</code> argument that has - * a sub UI element anywhere within its sub hierarchy that has text attribute - * <code>text</code>. The returned UiObject will point at the <code>childPattern</code> - * instance that matched the search and not at the text matched sub element</p> - * By default this operation will perform scroll search while attempting to find the UI - * element. + * 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 of the child pattern to match and return - * @param text String of the identifying child contents of of the <code>childPattern</code> - * @return {@link UiObject} pointing at and instance of <code>childPattern</code> + * @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 */ @@ -182,12 +190,17 @@ public class UiScrollable extends UiCollection { } /** - * See {@link #getChildByText(UiSelector, String)} - * - * @param childPattern {@link UiSelector} selector of the child pattern to match and return - * @param text String of the identifying child contents of of the <code>childPattern</code> + * 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} pointing at and instance of <code>childPattern</code> + * @return {@link UiObject} representing the child element that matches the search conditions * @throws UiObjectNotFoundException * @since API Level 16 */ @@ -204,11 +217,12 @@ public class UiScrollable extends UiCollection { } /** - * Performs a swipe Up on the UI element until the requested content-description - * is visible or until swipe attempts have been exhausted. See {@link #setMaxSearchSwipes(int)} + * 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 to look for anywhere within the contents of this scrollable. - * @return true if item us found else false + * @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 { @@ -217,8 +231,8 @@ public class UiScrollable extends UiCollection { } /** - * Perform a scroll search for a UI element matching the {@link UiSelector} selector argument. - * See {@link #scrollDescriptionIntoView(String)} and {@link #scrollTextIntoView(String)}. + * 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 @@ -230,11 +244,13 @@ public class UiScrollable extends UiCollection { } /** - * Perform a scroll search for a UI element matching the {@link UiSelector} selector argument. + * 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 + * @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 { @@ -263,13 +279,13 @@ public class UiScrollable extends UiCollection { } /** - * Ensures the child object is fully visible in the scrollable container + * 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. * - * Current implementation may actually scroll the item's edges off screen - * Current implementation does not check if the item can fully fit into the display area - * - * @param childSelector - * @return + * @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 */ @@ -306,11 +322,12 @@ public class UiScrollable extends UiCollection { } /** - * Performs a swipe up on the UI element until the requested text is visible - * or until swipe attempts have been exhausted. See {@link #setMaxSearchSwipes(int)} + * 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 to look for - * @return true if item us found else false + * @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 { @@ -319,13 +336,12 @@ public class UiScrollable extends UiCollection { } /** - * {@link #getChildByDescription(UiSelector, String)} and - * {@link #getChildByText(UiSelector, String)} 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 - * {@link #getMaxSearchSwipes()} + * 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 is the number of search swipes until abort + * @param swipes the number of search swipes to perform until giving up * @return reference to itself * @since API Level 16 */ @@ -336,13 +352,12 @@ public class UiScrollable extends UiCollection { } /** - * {@link #getChildByDescription(UiSelector, String)} and - * {@link #getChildByText(UiSelector, String)} 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 {@link #setMaxSearchSwipes(int)} + * 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 value of the number of swipes currently allowed during a scroll search + * @return max the number of search swipes to perform until giving up * @since API Level 16 */ public int getMaxSearchSwipes() { @@ -351,9 +366,14 @@ public class UiScrollable extends UiCollection { } /** - * A convenience version of {@link UiScrollable#scrollForward(int)}, performs a fling - * - * @return true if scrolled and false if can't scroll anymore + * 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 { @@ -362,9 +382,14 @@ public class UiScrollable extends UiCollection { } /** - * A convenience version of {@link UiScrollable#scrollForward(int)}, performs a regular scroll - * - * @return true if scrolled and false if can't scroll anymore + * 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 { @@ -373,14 +398,14 @@ public class UiScrollable extends UiCollection { } /** - * Perform a scroll forward. If this list is set to vertical (see {@link #setAsVerticalList()} - * default) then the swipes will be executed from the bottom to top. If this list is set - * to horizontal (see {@link #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. - * - * @param steps use steps to control the speed, so that it may be a scroll, or fling - * @return true if scrolled and false if can't scroll anymore + * 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 { @@ -420,9 +445,14 @@ public class UiScrollable extends UiCollection { } /** - * See {@link UiScrollable#scrollBackward(int)} - * - * @return true if scrolled and false if can't scroll anymore + * 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 { @@ -431,9 +461,14 @@ public class UiScrollable extends UiCollection { } /** - * See {@link UiScrollable#scrollBackward(int)} - * - * @return true if scrolled and false if can't scroll anymore + * 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 { @@ -442,14 +477,14 @@ public class UiScrollable extends UiCollection { } /** - * Perform a scroll backward. If this list is set to vertical (see {@link #setAsVerticalList()} - * default) then the swipes will be executed from the top to bottom. If this list is set - * to horizontal (see {@link #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. - * - * @param steps use steps to control the speed, so that it may be a scroll, or fling - * @return true if scrolled and false if can't scroll anymore + * 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 { @@ -491,9 +526,10 @@ public class UiScrollable extends UiCollection { } /** - * 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. + * 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 @@ -512,7 +548,10 @@ public class UiScrollable extends UiCollection { } /** - * See {@link UiScrollable#scrollToBeginning(int, int)} + * 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 @@ -524,7 +563,10 @@ public class UiScrollable extends UiCollection { } /** - * See {@link UiScrollable#scrollToBeginning(int, int)} + * 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 @@ -536,9 +578,10 @@ public class UiScrollable extends UiCollection { } /** - * 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. + * 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 @@ -556,10 +599,13 @@ public class UiScrollable extends UiCollection { } /** - * See {@link UiScrollable#scrollToEnd(int, int)} + * 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 + * @return true on scrolled, else false * @since API Level 16 */ public boolean scrollToEnd(int maxSwipes) throws UiObjectNotFoundException { @@ -568,10 +614,13 @@ public class UiScrollable extends UiCollection { } /** - * See {@link UiScrollable#scrollToEnd(int, int)} + * 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 + * @return true on scrolled, else false * @since API Level 16 */ public boolean flingToEnd(int maxSwipes) throws UiObjectNotFoundException { @@ -580,15 +629,12 @@ public class UiScrollable extends UiCollection { } /** - * Returns the percentage of a widget's size that's considered as no touch zone when swiping - * - * Dead zones are set as percentage of a widget's total width or height where - * swipe start point cannot start or swipe end point cannot end. It is like a margin - * around the actual dimensions of the widget. Swipes will always be 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 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 @@ -599,15 +645,13 @@ public class UiScrollable extends UiCollection { } /** - * Sets the percentage of a widget's size that's considered as no touch zone when swiping - * - * Dead zones are set as percentage of a widget's total width or height where - * swipe start point cannot start or swipe end point cannot end. It is like a margin - * around the actual dimensions of the widget. Swipes will 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 + * 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 @@ -618,4 +662,4 @@ public class UiScrollable extends UiCollection { mSwipeDeadZonePercentage = swipeDeadZonePercentage; return this; } -} + diff --git a/library/core-src/com/android/uiautomator/core/UiSelector.java b/library/core-src/com/android/uiautomator/core/UiSelector.java index b7f5fa7..a3b5c54 100644 --- a/library/core-src/com/android/uiautomator/core/UiSelector.java +++ b/library/core-src/com/android/uiautomator/core/UiSelector.java @@ -22,12 +22,10 @@ import android.view.accessibility.AccessibilityNodeInfo; import java.util.regex.Pattern; /** - * This class provides the mechanism for tests to describe the UI elements they - * intend to target. A UI element has many properties associated with it such as - * text value, content-description, class name and multiple state information like - * selected, enabled, checked etc. Additionally UiSelector allows targeting of UI - * elements within a specific display hierarchies to distinguish similar elements - * based in the hierarchies they're in. + * Specifies the elements in the layout hierarchy for tests to target, filtered + * by properties such as text value, content-description, class name, and state + * information. You can also target an element by its location in a layout + * hierarchy. * @since API Level 16 */ public class UiSelector { @@ -105,11 +103,10 @@ public class UiSelector { /** * Set the search criteria to match the visible text displayed - * for a widget (for example, the text label to launch an app). + * in a widget (for example, the text label to launch an app). * - * The text for the widget must match exactly - * with the string in your input argument. - * Matching is case-sensitive. + * The text for the element must match exactly with the string in your input + * argument. Matching is case-sensitive. * * @param text Value to match * @return UiSelector with the specified search criteria @@ -120,11 +117,11 @@ public class UiSelector { } /** - * Set the search criteria to match the visible text displayed - * for a widget (for example, the text label to launch an app). + * Set the search criteria to match the visible text displayed in a layout + * element, using a regular expression. * - * The text for the widget must match exactly - * with the string in your input argument. + * The text in the widget must match exactly with the string in your + * input argument. * * @param regex a regular expression * @return UiSelector with the specified search criteria @@ -135,15 +132,13 @@ public class UiSelector { } /** - * Text property is usually the widget's visible text on the display. - * - * Adding this to the search criteria indicates that the search performed - * should match a widget with text value starting with the text parameter. + * Set the search criteria to match visible text in a widget that is + * prefixed by the text parameter. * - * The matching will be case-insensitive. + * The matching is case-insensitive. * - * @param text - * @return UiSelector with this added search criterion + * @param text Value to match + * @return UiSelector with the specified search criteria * @since API Level 16 */ public UiSelector textStartsWith(String text) { @@ -151,11 +146,10 @@ public class UiSelector { } /** - * Set the search criteria to match the visible text displayed - * for a widget (for example, the text label to launch an app). + * Set the search criteria to match the visible text in a widget + * where the visible text must contain the string in your input argument. * - * The text for the widget must contain the string in - * your input argument. Matching is case-sensitive. + * The matching is case-sensitive. * * @param text Value to match * @return UiSelector with the specified search criteria @@ -179,7 +173,7 @@ public class UiSelector { /** * Set the search criteria to match the class property - * for a widget (for example, "android.widget.Button"). + * for a widget, using a regular expression. * * @param regex a regular expression * @return UiSelector with the specified search criteria @@ -284,9 +278,9 @@ public class UiSelector { } /** - * Set the search criteria to match the given resource id. + * Set the search criteria to match the given resource ID. * - * @param id value to match + * @param id Value to match * @return UiSelector with the specified search criteria * @since API Level 18 */ @@ -295,8 +289,8 @@ public class UiSelector { } /** - * Set the search criteria to match the resourceId - * of the widget + * Set the search criteria to match the resource ID + * of the widget, using a regular expression.http://blog.bettersoftwaretesting.com/ * * @param regex a regular expression * @return UiSelector with the specified search criteria @@ -1025,4 +1019,4 @@ public class UiSelector { builder.append("]"); return builder.toString(); } -} + |