Widgets and collections

UiObject

UiObject represents a widget. You can use it to read widget properties and perform actions such as click/long-click.

You usually obtain a UiObject via selector methods like findOne() / findOnce(). You can also get it from a UiCollection, or navigate via UiObject.child(), UiObject.parent() to reach children/parent widgets.

UiObject.click()

• Returns {boolean}

Click the widget and return whether the click succeeded.

If it returns false, the widget may not be clickable (clickable=false), or the current UI cannot respond to the click. In such cases you can try clickCenter().

UiObject.clickCenter()

[Added in Pro 8.8.17]

• Returns {boolean}

Click the center point of the widget by coordinates. Equivalent to click(uiObj.bounds().centerX(), uiObject.bounds().centerY()).

Returns whether the click succeeded.

UiObject.longClick()

• Returns {boolean}

Long-click the widget and return whether it succeeded.

If it returns false, the widget may not be long-clickable (longClickable=false), or the current UI cannot respond.

UiObject.setText(text)

• text {string} Text
• Returns {boolean}

Set the text of an input widget and return whether it succeeded.

Only works for editable input widgets (editable=true).

UiObject.copy()

• Returns {boolean}

Copy the currently selected text in an input widget and return whether it succeeded.

Only works for input widgets, and only when there is selected text. Use setSelection() to set the selection.

var et = className("EditText").findOne();
// Select the first 2 characters
et.setSelection(0, 2);
// Copy selected text
if (et.copy()) {
  toast("Copied");
} else {
  toast("Copy failed");
}

UiObject.cut()

Cut the currently selected text in an input widget and return whether it succeeded.

Only works for input widgets, and only when there is selected text. Use setSelection() to set the selection.

UiObject.paste()

• Returns {boolean}

Paste clipboard content into an input widget and return whether it succeeded.

// Set clipboard text
setClip("Hello");
var et = className("EditText").findOne();
et.paste();

UiObject.setSelection(start, end)

• start {number} Selection start index
• end {number} Selection end index (exclusive)
• Returns {boolean}

Set selection range in an input widget and return whether it succeeded.

Indices are 0-based, and the selection does not include the character at index end. For example, if the input text is "123456789", selecting "4567" is et.setSelection(3, 7).

You can also set the cursor position by setting end equal to start. For example, et.setSelection(1, 1) places the cursor after the first character.

UiObject.scrollForward()

• Returns {boolean}

Scroll forward and return whether it succeeded.

“Forward” includes scrolling right and scrolling down. If a widget supports both right and down scrolling, the behavior of scrollForward() is unspecified (Android docs do not clarify, and there isn't enough testing to guarantee it).

UiObject.scrollBackward()

• Returns {boolean}

Scroll backward and return whether it succeeded.

“Backward” includes scrolling left and scrolling up. If a widget supports multiple directions, behavior may be unspecified.

UiObject.select()

• Returns {boolean}

Perform a “select” action and return whether it succeeded. This relates to isSelected(), but is rarely used.

UiObject.collapse()

• Returns {boolean}

Collapse the widget and return whether it succeeded.

UiObject.expand()

• Returns {boolean}

Expand the widget and return whether it succeeded.

UiObject.show()

Show the widget and return whether it succeeded.

UiObject.scrollUp()

• Returns {boolean}

Scroll up and return whether it succeeded. (Some widgets look scrollable but scrollUp() may not work; try scrollBackward() instead.)

UiObject.scrollDown()

• Returns {boolean}

Scroll down and return whether it succeeded. (Some widgets look scrollable but scrollDown() may not work; try scrollForward() instead.)

UiObject.scrollLeft()

• Returns {boolean}

Scroll left and return whether it succeeded. (Some widgets look scrollable but scrollLeft() may not work; try scrollBackward() instead.)

UiObject.scrollRight()

• Returns {boolean}

Scroll right and return whether it succeeded. (Some widgets look scrollable but scrollRight() may not work; try scrollForward() instead.)

UiObject.scrollTo(row, column)

• row {number} Target row index
• column {number} Target column index
• Returns {boolean}

Scroll a scrollable widget to the specified row/column position. Whether it works depends on the widget.

UiObject.setProgress(progress)

• progress {number} Progress value
• Returns {boolean}

Set the progress value (e.g. progress bar, slider). Only works for widgets that support progress semantics.

UiObject.contextClick()

• Returns {boolean}

Perform a context click. Commonly used to open context menus or special click behaviors.

UiObject.dismiss()

• Returns {boolean}

Try to dismiss the widget (e.g. notifications, dismissable overlays) and return whether it succeeded.

UiObject.clearFocus()

• Returns {boolean}

Clear focus and return whether it succeeded.

UiObject.clearAccessibilityFocus()

• Returns {boolean}

Clear accessibility focus and return whether it succeeded.

UiObject.children()

• Returns {UiCollection}

Return a collection of all child widgets. Useful for iterating children, for example:

className("AbsListView")
  .findOne()
  .children()
  .forEach(function (child) {
    log(child.className());
  });

UiObject.childCount()

• Returns {number}

Return the number of child widgets.

UiObject.child(i)

• i {number} Child index
• Returns {UiObject}

Return the ((i + 1))-th child widget. If i is out of range ((i \ge) child count or (i \lt 0)), an exception is thrown.

Note: due to layout capture limitations, this function may return null (a child may not be obtainable).

Example (iterate children):

var list = className("AbsListView").findOne();
for (var i = 0; i < list.childCount(); i++) {
  var child = list.child(i);
  log(child.className());
}

UiObject.parent()

• Returns {UiObject}

Return the parent widget. If there is no parent, returns null.

UiObject.bounds()

• Returns {Rect}

Return the widget bounds on the screen, as a Rect object.

Example:

var b = text("Auto.js").findOne().bounds();
toast("Widget bounds on screen: " + b);

If a widget cannot be clicked via click(), you can get its bounds and click by coordinates. Example:

var b = desc("Open side menu").findOne().bounds();
click(b.centerX(), b.centerY());
// If using root, use Tap(b.centerX(), b.centerY());

UiObject.boundsInParent()

• Returns {Rect}

Return the widget bounds within its parent, as a Rect object.

UiObject.drawingOrder()

• Returns {number}

Return the drawing order within its parent. Only works on Android 7.0+; on lower versions it returns 0.

UiObject.id()

• Returns {string}

Get the widget id. If it has no id, returns null.

UiObject.text()

• Returns {string}

Get the widget text. If there is no text, returns "".

UiObject.findByText(str)

• str {string} Text
• Returns {UiCollection}

Recursively search children for widgets whose text or desc contains str, and return them as a collection.

This searches children, grandchildren, and deeper descendants for matches.

UiObject.findOne(selector)

• selector {UiSelector}
• Returns {UiObject}

Search this widget's descendants using selector, and return the first matching widget; if none is found, return null.

Example: in a feed list, you can iterate items and “like” items whose like count is below 10:

// Find the feed list
var list = id("recycler_view").findOne();
// Iterate items
list.children().forEach(function (child) {
  // Find like icon
  var like = child.findOne(id("feed_action_view_like"));
  // Find like count
  var likeCount = child.findOne(id("text_view"));
  // Skip if not found
  if (like == null || likeCount == null) {
    return;
  }
  // If like count < 10
  if (parseInt(likeCount.text()) < 10) {
    // Like
    like.click();
  }
});

UiObject.find(selector)

• selector {UiSelector}
• Returns {UiCollection}

Search this widget's descendants using selector and return all matching widgets as a collection.

UiCollection

UiCollection is a widget collection returned by selector methods like find() and untilFind().

UiCollection “inherits” from Array. In practice, it is an array of UiObject, so you can use array functions/properties such as length and forEach.

For example, use forEach to traverse all TextView widgets and print their text:

console.show();
className("TextView")
  .find()
  .forEach(function (tv) {
    if (tv.text() != "") {
      log(tv.text());
    }
  });

You can also iterate with a traditional for loop:

console.show();
var uc = className("TextView").find();
for (var i = 0; i < uc.length; i++) {
  var tv = uc[i];
  if (tv.text() != "") {
    log(tv.text());
  }
}

Each element in a UiCollection is a UiObject. You can operate on a single element, e.g. uc[0].click(). If you want to operate on all elements, call methods on the collection directly, e.g. uc.click(), which clicks all UiObjects and returns whether all clicks succeeded.

Therefore, UiCollection supports the same widget-operation methods as UiObject (such as click(), longClick(), scrollForward(), etc.).

UiCollection.size()

• Returns {number}

Return the number of widgets in the collection.

Legacy function; equivalent to the length property.

UiCollection.get(i)

• i {number} Index
• Returns {UiObject}

Return the ((i + 1))-th widget (UiObject) in the collection.

Legacy function; prefer using array indexing.

UiCollection.each(func)

• func {Function} Iterate function. Argument is UiObject.

Iterate the collection.

Legacy function; equivalent to forEach. See forEach.

UiCollection.empty()

• Returns {boolean}

Return whether the collection is empty.

UiCollection.nonEmpty()

• Returns {boolean}

Return whether the collection is non-empty.

UiCollection.find(selector)

• selector {UiSelector}
• Returns {UiCollection}

Find all widgets that match selector within widgets in this collection and their descendants, and return them as a collection.

Note: this recursively traverses all widgets in the collection and their descendants. This is different from Array filter().

Example:

var names = id("name").find();
// Within the collection
var clickableNames = names.find(clickable());

UiCollection.findOne(selector)

• selector {UiSelector}
• Returns {UiObject}

Search descendants of widgets in this collection using selector, and return the first match; if none is found, return null.