Merge "docs: Edited Javadoc comments in uiautomator library source files (MR2)." into jb-mr2-dev
diff --git a/uiautomator/library/core-src/com/android/uiautomator/core/Configurator.java b/uiautomator/library/core-src/com/android/uiautomator/core/Configurator.java
index 55ed3e7..5f62fc3 100644
--- a/uiautomator/library/core-src/com/android/uiautomator/core/Configurator.java
+++ b/uiautomator/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 @@
}
/**
- * Retrieves a singleton instance of Configurator
+ * Retrieves a singleton instance of Configurator.
*
* @return Configurator instance
* @since API Level 18
@@ -55,11 +59,15 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 long getKeyInjectionDelay() {
return mKeyInjectionDelay;
}
-}
+
diff --git a/uiautomator/library/core-src/com/android/uiautomator/core/UiDevice.java b/uiautomator/library/core-src/com/android/uiautomator/core/UiDevice.java
index fc23cdf..9b69d62 100644
--- a/uiautomator/library/core-src/com/android/uiautomator/core/UiDevice.java
+++ b/uiautomator/library/core-src/com/android/uiautomator/core/UiDevice.java
@@ -90,13 +90,14 @@
}
/**
- * 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) {
@@ -343,7 +344,7 @@
}
/**
- * Opens the notification shade
+ * Opens the notification shade.
*
* @return true if successful, else return false
* @since API Level 18
@@ -355,7 +356,7 @@
}
/**
- * Opens the quick settings shade
+ * Opens the Quick Settings shade.
*
* @return true if successful, else return false
* @since API Level 18
@@ -430,16 +431,18 @@
}
/**
- * 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) {
@@ -845,4 +848,4 @@
Tracer.trace(storePath, scale, quality);
return getAutomatorBridge().takeScreenshot(storePath, quality);
}
-}
+
diff --git a/uiautomator/library/core-src/com/android/uiautomator/core/UiObject.java b/uiautomator/library/core-src/com/android/uiautomator/core/UiObject.java
index 4862ca5..d9ba745 100644
--- a/uiautomator/library/core-src/com/android/uiautomator/core/UiObject.java
+++ b/uiautomator/library/core-src/com/android/uiautomator/core/UiObject.java
@@ -25,11 +25,11 @@
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 {
@@ -69,8 +69,8 @@
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
*/
@@ -102,7 +102,7 @@
/**
* Retrieves the {@link InteractionController} to perform finger actions such as tapping,
- * swiping or entering text.
+ * swiping, or entering text.
*
* @return {@link InteractionController}
*/
@@ -111,11 +111,10 @@
}
/**
- * 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 {
@@ -124,13 +123,11 @@
}
/**
- * 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
*/
@@ -140,10 +137,9 @@
}
/**
- * 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
*/
@@ -157,8 +153,8 @@
}
/**
- * 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
@@ -185,13 +181,14 @@
}
/**
- * 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
*/
@@ -203,14 +200,15 @@
}
/**
- * 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
*/
@@ -221,9 +219,14 @@
}
/**
- * 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.
@@ -242,12 +245,16 @@
}
/**
- * 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.
@@ -266,12 +273,16 @@
}
/**
- * 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.
@@ -289,12 +300,16 @@
}
/**
- * 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.
@@ -343,10 +358,10 @@
}
/**
- * 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.
@@ -382,9 +397,9 @@
}
/**
+ * 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
@@ -525,10 +540,10 @@
}
/**
- * 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 {
@@ -635,7 +650,7 @@
}
/**
- * 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
@@ -651,7 +666,7 @@
}
/**
- * 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
@@ -667,7 +682,7 @@
}
/**
- * 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
@@ -683,7 +698,7 @@
}
/**
- * 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
@@ -715,7 +730,7 @@
}
/**
- * 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
@@ -731,7 +746,7 @@
}
/**
- * 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
@@ -747,7 +762,7 @@
}
/**
- * 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
@@ -763,7 +778,7 @@
}
/**
- * 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
@@ -779,9 +794,9 @@
}
/**
- * 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
@@ -799,7 +814,7 @@
}
/**
- * 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
@@ -818,14 +833,14 @@
}
/**
- * 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) {
@@ -837,12 +852,12 @@
}
/**
- * 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.
*
@@ -869,14 +884,14 @@
}
/**
- * 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() {
@@ -891,14 +906,14 @@
}
/**
- * 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
*/
@@ -930,14 +945,13 @@
}
/**
- * 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
*/
@@ -967,16 +981,16 @@
}
/**
- * 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,
@@ -1042,15 +1056,13 @@
}
/**
- * 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;
@@ -1058,14 +1070,14 @@
* 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/uiautomator/library/core-src/com/android/uiautomator/core/UiScrollable.java b/uiautomator/library/core-src/com/android/uiautomator/core/UiScrollable.java
index f5306af..9b14c10 100644
--- a/uiautomator/library/core-src/com/android/uiautomator/core/UiScrollable.java
+++ b/uiautomator/library/core-src/com/android/uiautomator/core/UiScrollable.java
@@ -20,8 +20,9 @@
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 @@
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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * See {@link #getChildByDescription(UiSelector, String)}
+ * 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} 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.
+ * @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 @@
}
/**
- * 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.
+ * 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} 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>
+ * @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 @@
}
/**
- * 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 @@
}
/**
- * See {@link #getChildByText(UiSelector, String)}
+ * 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 of the child pattern to match and return
- * @param text String of the identifying child contents of of the <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
* @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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * {@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 @@
}
/**
- * {@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 @@
}
/**
- * A convenience version of {@link UiScrollable#scrollForward(int)}, performs a fling
+ * 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 and false if can't scroll anymore
+ * @return true if scrolled, false if can't scroll anymore
* @since API Level 16
*/
public boolean flingForward() throws UiObjectNotFoundException {
@@ -362,9 +382,14 @@
}
/**
- * A convenience version of {@link UiScrollable#scrollForward(int)}, performs a regular scroll
+ * 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 and false if can't scroll anymore
+ * @return true if scrolled, false if can't scroll anymore
* @since API Level 16
*/
public boolean scrollForward() throws UiObjectNotFoundException {
@@ -373,14 +398,14 @@
}
/**
- * 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.
+ * 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 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
+ * @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 @@
}
/**
- * See {@link UiScrollable#scrollBackward(int)}
+ * 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
+ * @return true if scrolled, and false if can't scroll anymore
* @since API Level 16
*/
public boolean flingBackward() throws UiObjectNotFoundException {
@@ -431,9 +461,14 @@
}
/**
- * See {@link UiScrollable#scrollBackward(int)}
+ * 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
+ * @return true if scrolled, and false if can't scroll anymore
* @since API Level 16
*/
public boolean scrollBackward() throws UiObjectNotFoundException {
@@ -442,14 +477,14 @@
}
/**
- * 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.
+ * 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 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
+ * @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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
mSwipeDeadZonePercentage = swipeDeadZonePercentage;
return this;
}
-}
+
diff --git a/uiautomator/library/core-src/com/android/uiautomator/core/UiSelector.java b/uiautomator/library/core-src/com/android/uiautomator/core/UiSelector.java
index b7f5fa7..a3b5c54 100644
--- a/uiautomator/library/core-src/com/android/uiautomator/core/UiSelector.java
+++ b/uiautomator/library/core-src/com/android/uiautomator/core/UiSelector.java
@@ -22,12 +22,10 @@
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 @@
/**
* 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 @@
}
/**
- * 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 @@
}
/**
- * Text property is usually the widget's visible text on the display.
+ * Set the search criteria to match visible text in a widget that is
+ * prefixed by the text parameter.
*
- * Adding this to the search criteria indicates that the search performed
- * should match a widget with text value starting with the text parameter.
+ * The matching is case-insensitive.
*
- * The matching will be 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 @@
}
/**
- * 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 @@
/**
* 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
builder.append("]");
return builder.toString();
}
-}
+
