Class: UIAutomation::ElementArray

Inherits:
RemoteProxy show all
Includes:
Enumerable
Defined in:
lib/ui_automation/element_array.rb

Overview

Represents objects of type UIAElementArray in the Javascript API.

An ElementArray represents a collection of elements of a specific type within the view hierarchy.

This class implements #each and includes the Enumerable mixin, enabling you to use it like any other native Ruby collection class.

All methods in thie class that return a UIAutomation::Element may return a specific sub-class of UIAutomation::Element, as determined by the #element_klass attribute.

Instance Attribute Summary collapse

Accessing Elements collapse

Instance Method Summary collapse

Methods inherited from RemoteProxy

#execute_self, #fetch, from_element_id, from_javascript, #perform, #proxy_for, #to_javascript, #to_s

Constructor Details

#initialize(executor, remote_object, element_klass = UIAutomation::Element, parent_element = nil, window = nil) ⇒ ElementArray

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of ElementArray.


30
31
32
33
34
35
# File 'lib/ui_automation/element_array.rb', line 30

def initialize(executor, remote_object, element_klass = UIAutomation::Element, parent_element = nil, window = nil)
  super executor, remote_object
  @element_klass = element_klass
  @parent = parent_element
  @window = window
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class UIAutomation::RemoteProxy

Instance Attribute Details

#element_klassvoid (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The element proxy class used for each element in the array.


27
28
29
# File 'lib/ui_automation/element_array.rb', line 27

def element_klass
  @element_klass
end

#parentUIAutomation::Element (readonly)

Note:

This returns the existing proxy that created this one; it does not use the UIAElement.parent() method

The proxy for the parent element


19
20
21
# File 'lib/ui_automation/element_array.rb', line 19

def parent
  @parent
end

#windowUIAutomation::Window (readonly)

The window that contains this element


23
24
25
# File 'lib/ui_automation/element_array.rb', line 23

def window
  @window
end

Instance Method Details

#[](index_or_name) ⇒ UIAutomation::Element

Returns a remote proxy to a specific element within the collection by index or name.

You can use square-bracked syntax with either an Integer or String key to perform lookup by index or name respectively.

Calling with an Integer is equivalent to calling #at_index. Calling with a String is equivalent to calling #first_with_name.

Parameters:

  • index_or_name (String or Integer)

    the index or name of the attribute

Returns:

See Also:

  • UIAElementArray.withName()

149
150
151
152
153
154
155
# File 'lib/ui_automation/element_array.rb', line 149

def [](index_or_name)
  if index_or_name.is_a?(Integer)
    at_index(index_or_name)
  else
    first_with_name(index_or_name)
  end
end

#at_index(index) ⇒ UIAutomation::Element

Returns a proxy to the element at the given index.

Parameters:

  • index (Integer)

Returns:


48
49
50
# File 'lib/ui_automation/element_array.rb', line 48

def at_index(index)
  build_proxy element_klass, remote_object.object_for_subscript(index), [parent, window]
end

#each {|element| ... } ⇒ Enumerator

Yields a proxy to each element in the ElementArray if a block is given.

If no block is given, this method will return an Enumerator.

Yield Parameters:

Returns:

  • (Enumerator)

    if no block is given


174
175
176
177
178
179
180
181
182
# File 'lib/ui_automation/element_array.rb', line 174

def each(&block)
  if block_given?
    (0...length).each do |index|
      yield self[index]
    end
  else
    to_enum(:each)
  end
end

#first_with_name(name) ⇒ UIAutomation::Element

Returns a proxy to the first element with the given name.

Parameters:

  • name (String)

Returns:

See Also:

  • UIAElementArray.firstWithName()

68
69
70
# File 'lib/ui_automation/element_array.rb', line 68

def first_with_name(name)
  element_proxy_for :firstWithName, name
end

#first_with_predicate(template, substitutions = {}) ⇒ UIAutomation::Element

Returns a proxy to the first element matching the specified predicate.

Predicates use the Apple NSPredicate syntax (see #with_predicate for more information).

Parameters:

  • template (String)

    a predicate template using NSPredicate syntax

  • substitutions (Hash) (defaults to: {})

    an optional hash of template substitutions

Returns:

See Also:


102
103
104
# File 'lib/ui_automation/element_array.rb', line 102

def first_with_predicate(template, substitutions = {})
  element_proxy_for :firstWithPredicate, UIAutomation::PredicateString.new(template, substitutions).to_s
end

#first_with_value(value) ⇒ UIAutomation::Element

Returns a proxy to the first element with the given value.

Parameters:

  • value (Object)

    the element value

Returns:

See Also:

  • UIAElementArray.firstWithName()

132
133
134
135
# File 'lib/ui_automation/element_array.rb', line 132

def first_with_value(value)
  collection = with_value(value)
  collection.any? ? collection.first : nil
end

#inspectvoid


37
38
39
# File 'lib/ui_automation/element_array.rb', line 37

def inspect
  "<RemoteProxy(#{self.class.name}) type:#{element_klass}: #{to_javascript}>"
end

#lengthInteger Also known as: count

Returns the number of items in the array

Returns:

  • (Integer)

162
163
164
# File 'lib/ui_automation/element_array.rb', line 162

def length
  fetch(:length)
end

#with_name(name) ⇒ UIAutomation::ElementArray

Returns a new ElementArray containing all elements with the given name.

Parameters:

  • name (String)

Returns:

See Also:

  • UIAElementArray.withName()

58
59
60
# File 'lib/ui_automation/element_array.rb', line 58

def with_name(name)
  element_array_proxy_for :withName, name
end

#with_predicate(template, substitutions = {}) ⇒ UIAutomation::ElementArray

Returns a new ElementArray containing all elements matching the given predicate.

Predicates use the Apple NSPredicate syntax.

To avoid dealing with escaping and quoting of string values, you can use template substitution in your predicate string and pass in the values as a hash.

Examples:

Using predicate template substitution

array.with_predicate("name beginswith :value", :value => 'test')

Parameters:

  • template (String)

    a predicate template using NSPredicate syntax

  • substitutions (Hash) (defaults to: {})

    an optional hash of template substitutions

Returns:

See Also:


88
89
90
# File 'lib/ui_automation/element_array.rb', line 88

def with_predicate(template, substitutions = {})
  element_array_proxy_for :withPredicate, UIAutomation::PredicateString.new(template, substitutions).to_s
end

#with_value(value) ⇒ UIAutomation::ElementArray

Returns a new ElementArray containing all elements with the given value.

Parameters:

  • value (Object)

Returns:


122
123
124
# File 'lib/ui_automation/element_array.rb', line 122

def with_value(value)
  with_value_for_key(:value, value)
end

#with_value_for_key(key, value) ⇒ UIAutomation::ElementArray

Returns a new ElementArray containing all elements with the given key/value pair.

Parameters:

  • key (String)
  • value (Object)

Returns:

See Also:

  • UIAElementArray.withValueForKey()

113
114
115
# File 'lib/ui_automation/element_array.rb', line 113

def with_value_for_key(key, value)
  element_array_proxy_for :withValueForKey, value, key
end