iOS Developer Library

Developer

UIAElementArray Class Reference

Options
Deployment Target:

On This Page

UIAElementArray

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable Not Applicable

Availability


Available in iOS 4.0 and later.

The UIAElementArray class supports operations with arrays containing multiple UIAElement objects. You can search the array by name or key/value pairs, or by custom criteria that you specify using a predicate. For detailed information about using predicates, see Predicates Programming Guide.

UIAElementArray supports the traditional shorthand syntax for accessing items in native JavaScript objects:

  • dot reference by element name, for example:

    var okButton = buttons.OK;

  • bracket reference by index, for example:

    var firstElement = elements[0];

  • bracket reference by element name, for example:

    var helloWorldText = staticTexts["Hello World"];

It is important to note one potentially confusing limitation in using bracket references by element name. If the name of an element happened to be a number, JavaScript would interpret that name as an index, likely yielding incorrect results. For example, consider this array:

var elements = ["DoIt", "Cancel", "1"];

If you attempt to access the third element by name with the bracket reference syntax:

elements()["1"]

it is actually treated as a reference to the first element, yielding the first element (named “DoIt”) instead. In cases where this problem might occur, you should use the dot reference syntax instead:

elements().firstWithName("1")

For an explanation of how to use this class and related classes, see Automating UI Testing in Instruments User Guide.

  • length Property

    Returns the number of user interface elements in the array.

    Declaration

    JavaScript

    (Number) length

  • Returns the first element in the array with this name.

    Declaration

    JavaScript

    (UIAElement) firstWithName(String name)

    Parameters

    name

    A string whose value is the name of the element match on.

    Availability

    Available in iOS 4.0 and later.

  • Returns the first element in the array matching the given criteria.

    Declaration

    JavaScript

    (UIAElement) firstWithPredicate(PredicateString predicateString)

    Parameters

    predicateString

    A predicate specifying the criteria to match.

    Discussion

    For detailed information about predicate matching, see Predicate Programming Guide.

    Availability

    Available in iOS 4.0 and later.

  • Returns the first element in the array with a value that matches the property key.

    Declaration

    JavaScript

    (UIAElement) firstWithValueForKey(NotTyped value, String key)

    Availability

    Available in iOS 4.0 and later.

  • Converts the array into a standard JavaScript array.

    Declaration

    JavaScript

    (Array) toArray()

    Availability

    Available in iOS 4.0 and later.

  • Returns all elements in the array with this name.

    Declaration

    JavaScript

    (UIAElementArray) withName(String name)

    Availability

    Available in iOS 4.0 and later.

  • Returns all elements in the array matching the given.

    Declaration

    JavaScript

    (UIAElementArray) withPredicate(PredicateString predicateString)

    Discussion

    Predicate matching follows the same rules as NSPredicate.

    Availability

    Available in iOS 4.0 and later.

  • Returns all elements in the array with a value that matches the property key.

    Declaration

    JavaScript

    (UIAElementArray) withValueForKey(NotTyped value, String key)

    Parameters

    value

    A string specifying the value that the specified property, if it exists, should match.

    key

    A string specifying the property to test for.

    Availability

    Available in iOS 4.0 and later.

Constants

  • Declaration

    Constants

    • UIAElementNil

      UIAElementNil

      Returned by a function with return type UIAElement or UIAElementArray if the requested element is not available after the timeout grace period you specify. This mechanism allows your scripting expressions to complete even if an intermediate function in the expression fails temporarily during the grace period. For example, the following code does not raise an exception if the navigation bar does not exist; instead it returns UIAElementNil.

      • var backButton = UIATarget.localTarget().frontMostApp().navigationBar().buttons()["Back"];
      • if (backButton.isValid()) {
      • backButton.tap();
      • } else {
      • UIALogger.logError("Could not find 'Back' button!");
      • }

      Available in iOS 4.0 and later.