AXElements 0.8.1 → 0.9.0

data/lib/accessibility/enumerators.rb

@@ -8,7 +8,7 @@ module Accessibility::Enumerators
   class BreadthFirst
     include Enumerable
 
-    # @param [#children]
+    # @param root [#children]
     def initialize root
       @root = root
     end
@@ -16,16 +16,14 @@ module Accessibility::Enumerators
     ##
     # Semi-lazily iterate through the tree.
     #
+    # @yield An element in the UI hierarchy
     # @yieldparam [AX::Element,AXUIElementRef]
     def each
-      # @todo mutate the array less, perhaps use an index instead
-      #       of #shift, then the array only grows
       queue = [@root]
       until queue.empty?
-        queue.shift.children.each do |x|
-          queue << x
-          yield x
-        end
+        kids = queue.shift.children
+        kids.each do |x| yield x end
+        queue.concat kids
       end
     end
 
@@ -38,6 +36,9 @@ module Accessibility::Enumerators
     #       being used...yet.
     #
     # Override `Enumerable#find` for performance reasons.
+    #
+    # @yield An element in the UI hierarchy
+    # @yieldparam [AX::Element,AXUIElementRef]
     def find
       each { |x| return x if yield x }
     end
@@ -50,11 +51,12 @@ module Accessibility::Enumerators
   class DepthFirst
     include Enumerable
 
-    # @param [#children]
+    # @param root [#children]
     def initialize root
       @root = root
     end
 
+    # @yield An element in the UI hierarchy
     # @yieldparam [AX::Element,AXUIElementRef]
     def each
       stack = @root.children
@@ -70,6 +72,7 @@ module Accessibility::Enumerators
     # Walk the UI element tree and yield both the element and the
     # level that the element is at relative to the root.
     #
+    # @yield An element in the UI hierarchy
     # @yieldparam [AX::Element,AXUIElementRef]
     # @yieldparam [Number]
     def each_with_level &block
@@ -85,9 +88,9 @@ module Accessibility::Enumerators
     ##
     # Recursive implementation of a depth first iterator.
     #
-    # @param [AX::Element]
-    # @param [Number]
-    # @param [#call]
+    # @param element [AX::Element]
+    # @param depth [Number]
+    # @param block [#call]
     def recursive_each_with_level element, depth, block
       block.call element, depth
       element.children.each do |x|

data/lib/accessibility/errors.rb

@@ -4,9 +4,10 @@ require 'accessibility/qualifier'
 # Error raised when an implicit search fails to return a result.
 class Accessibility::SearchFailure < NoMethodError
 
-  # @param [AX::Element]
-  # @param [#to_s]
-  # @param [Hash{Symbol=>Object}]
+  # @param searcher [AX::Element]
+  # @param searchee [#to_s]
+  # @param filters [Hash{Symbol=>Object}]
+  # @yield Optional block that would have been used for a search filter
   def initialize searcher, searchee, filters, &block
     filters = {} unless filters.kind_of? Hash
     msg  = "Could not find `#{pp_searchee searchee, filters, &block}` "

data/lib/accessibility/factory.rb

@@ -3,112 +3,27 @@ require 'accessibility/translator'
 
 ##
 # Namespace container for all the accessibility objects.
-module AX; end
+module AX; class Element; end end
 
-##
-# Mixin made for processing low level data from AXAPI methods.
-module Accessibility::Factory
-
-  # @todo This should provide alternate #to_ruby functionality for
-  #       the __NSCFType class in order to avoid the overhead of
-  #       checking type information (or at least reducing it).
-  #       However, it will force the lower level to always wrap
-  #       element references; this should be ok most of the time
-  #       but makes testing a bit of a pain...hmmm
-
-  ##
-  # Processes any given data from an AXAPI function and wraps it if
-  # needed. Meant for taking a return value from
-  # {Accessibility::Core#attribute} and friends.
-  #
-  # Generally, used to process an `AXUIElementRef` into a some kind
-  # of {AX::Element} subclass.
-  def process value
-    return nil if value.nil? # CFGetTypeID(nil) crashes runtime
-    case CFGetTypeID(value)
-    when ARRAY_TYPE then process_array value
-    when REF_TYPE   then process_element value
-    else
-      value
-    end
-  end
 
-
-  private
+class << AX
 
   ##
   # @private
   #
-  # Reference to the singleton instance of the translator.
+  # Mutex to make sure we only create one class at a time.
   #
-  # @return [Accessibility::Translator]
-  TRANSLATOR = Accessibility::Translator.instance
+  # @return [Mutex]
+  MUTEX = Mutex.new
 
   ##
   # @private
   #
-  # Type ID for `AXUIElementRef` objects.
+  # Find the class for a given role
   #
-  # @return [Number]
-  REF_TYPE   = AXUIElementGetTypeID()
-
-  ##
-  # @private
-  #
-  # Type ID for `CFArrayRef` objects.
+  # If the class does not exist it will be created.
   #
-  # @return [Number]
-  ARRAY_TYPE = CFArrayGetTypeID()
-
-  ##
-  # @todo Should we handle cases where a subrole has a value of
-  #       'Unknown'? What is the performance impact?
-  #
-  # Takes an `AXUIElementRef` and gives you some kind of wrapped
-  # accessibility object.
-  #
-  # Some code paths have been unrolled for efficiency. Don't hate player,
-  # hate the game.
-  #
-  # @param [AXUIElementRef]
-  # @return [AX::Element]
-  def process_element ref
-    if role = ref.role
-      role  = TRANSLATOR.unprefix role
-      attrs = ref.attributes
-      if attrs.include? KAXSubroleAttribute
-        subrole = ref.subrole
-        # Some objects claim to have a subrole but return nil
-        if subrole
-          class_for2(TRANSLATOR.unprefix(subrole), role).new ref
-        else
-          class_for(role).new ref
-        end
-      else
-        class_for(role).new ref
-      end
-    else # failsafe in case object dies before we even get the role
-      AX::Element.new ref
-    end
-  end
-
-  ##
-  # We assume a homogeneous array and only wrap element arrays right now.
-  #
-  # @return [Array]
-  def process_array vals
-    return vals if vals.empty?
-    return vals if CFGetTypeID(vals.first) != REF_TYPE
-    return vals.map { |val| process_element val }
-  end
-
-  ##
-  # @todo Consider using {AX.const_missing} instead.
-  #
-  # Find the class for a given role. If the class does not exist it will
-  # be created on demand.
-  #
-  # @param [#to_s]
+  # @param role [#to_s]
   # @return [Class]
   def class_for role
     if AX.const_defined? role, false
@@ -119,14 +34,16 @@ module Accessibility::Factory
   end
 
   ##
-  # Find the class for a given subrole and role. If the class does not
-  # exist it will be created on demand.
+  # @private
   #
-  # @param [#to_s]
-  # @param [#to_s]
+  # Find the class for a given subrole and role
+  #
+  # If the class does not exist it will be created on demand.
+  #
+  # @param subrole [#to_s]
+  # @param role [#to_s]
   # @return [Class]
   def class_for2 subrole, role
-    # @todo it would be nice if we didn't have to lookup twice
     if AX.const_defined? subrole, false
       AX.const_get subrole
     else
@@ -135,29 +52,163 @@ module Accessibility::Factory
   end
 
   ##
-  # Create a new class in the {AX} namespace that has {AX::Element}
-  # as the superclass.
+  # @private
+  #
+  # Create a class in the {AX} namespace that has {AX::Element} as the
+  # superclass
   #
-  # @param [#to_s]
+  # @param name [#to_s]
   # @return [Class]
   def create_class name
-    klass = Class.new AX::Element
-    AX.const_set name, klass
+    MUTEX.synchronize do
+      # re-check now that we are in the critical section
+      @klass = if AX.const_defined? name, false
+                 AX.const_get name
+               else
+                 klass = Class.new AX::Element
+                 AX.const_set name, klass
+               end
+    end
+    @klass
   end
 
   ##
+  # @private
+  #
   # Create a new class in the {AX} namesapce that has the given
-  # `superklass` as the superclass..
+  # `superklass` as the superclass
   #
-  # @param [#to_s] name
-  # @param [#to_s] superklass
+  # @param name [#to_s]
+  # @param superklass [#to_s]
   # @return [Class]
   def create_class2 name, superklass
     unless AX.const_defined? superklass, false
       create_class superklass
     end
-    klass = Class.new AX.const_get(superklass)
-    AX.const_set name, klass
+    MUTEX.synchronize do
+      # re-check now that we are in the critical section
+      @klass = if AX.const_defined? name, false
+                 AX.const_get name
+               else
+                 klass = Class.new AX.const_get(superklass)
+                 AX.const_set name, klass
+               end
+    end
+    @klass
+  end
+
+end
+
+
+if on_macruby?
+
+  ##
+  # Extensions to {Accessibility::Element} for the higher level abstractions
+  #
+  # These extensions only make sense in the context of the high level API
+  # but needs to be applied on the lower level class, so the code has been
+  # placed in its own file.
+  module Accessibility::Element
+
+    ##
+    # @todo Should we handle cases where a subrole has a value of
+    #       'Unknown'? What is the performance impact?
+    #
+    # Wrap the low level wrapper with the appropriate high level wrapper.
+    # This involves determining the proper class in the {AX} namespace,
+    # possibly creating it on demand, and then instantiating the class to
+    # wrap the low level object.
+    #
+    # Some code paths have been unrolled for efficiency. Don't hate player,
+    # hate the game.
+    #
+    # @return [AX::Element]
+    def to_ruby
+      type = AXValueGetType(self)
+      if type.zero?
+        to_element
+      else
+        to_box type
+      end
+    end
+
+
+    private
+
+    ##
+    # @private
+    #
+    # Reference to the singleton instance of the translator.
+    #
+    # @return [Accessibility::Translator]
+    TRANSLATOR = Accessibility::Translator.instance
+
+    def to_box type
+      ptr = Pointer.new ValueWrapper::BOX_TYPES[type]
+      AXValueGetValue(self, type, ptr)
+      ptr.value.to_ruby
+    end
+
+    def to_element
+      if roll = self.role
+        roll = TRANSLATOR.unprefix roll
+        if attributes.include? KAXSubroleAttribute
+          subroll = self.subrole
+          # Some objects claim to have a subrole but return nil
+          if subroll
+            AX.class_for2(TRANSLATOR.unprefix(subroll), roll).new self
+          else
+            AX.class_for(roll).new self
+          end
+        else
+          AX.class_for(roll).new self
+        end
+      else # failsafe in case object dies before we get the role
+        AX::Element.new self
+      end
+    end
+
+  end
+
+
+else
+
+
+  ##
+  # `AXElements` extensions to the `Accessibility::Element` class
+  class Accessibility::Element
+
+    ##
+    # Override the default `#to_ruby` so that proper classes are
+    # chosen for each object.
+    #
+    # @return [AX::Element]
+    def to_ruby
+      if roll = self.role
+        roll = TRANSLATOR.unprefix roll
+        if attributes.include? KAXSubroleAttribute
+          subroll = self.subrole
+          # Some objects claim to have a subrole but return nil
+          if subroll
+            AX.class_for2(TRANSLATOR.unprefix(subroll), roll).new self
+          else
+            AX.class_for(roll).new self
+          end
+        else
+          AX.class_for(roll).new self
+        end
+      else # failsafe in case object dies before we get the role
+        AX::Element.new self
+      end
+    end
+
+    ##
+    # @private
+    #
+    # Reference to the singleton instance of the translator.
+    #
+    # @return [Accessibility::Translator]
+    TRANSLATOR = Accessibility::Translator.instance
   end
 
 end

data/lib/accessibility/graph.rb

@@ -31,7 +31,7 @@ class Accessibility::Graph
     # @return [AX::Element]
     attr_reader :element
 
-    # @param [AX::Element]
+    # @param element [AX::Element]
     def initialize element
       @element = element
       @id      = "element_#{element.object_id}"
@@ -47,7 +47,7 @@ class Accessibility::Graph
 
     def identifier
       klass = @element.class.to_s.split(NAMESPACE).last
-      ident = @element.pp_identifier.dup
+      ident = @element.pp_identifier.to_s.dup
       if ident.length > 12
         ident = "#{ident[0...12]}..."
       end
@@ -58,9 +58,13 @@ class Accessibility::Graph
     end
 
     def shape
-      (@element.attribute(:focused) && OCTAGON) ||
-      (@element.actions.empty? && OVAL)         ||
-      BOX
+      if @element.attributes.include?(:focused) && @element.attribute(:focused)
+        OCTAGON
+      elsif @element.actions.empty?
+        OVAL
+      else
+        BOX
+      end
     end
 
     def style
@@ -69,7 +73,7 @@ class Accessibility::Graph
         return FILLED unless @element.attribute(:enabled)
       end
       # bold if focused and no children
-      if @element.attribute(:focused)
+      if @element.attributes.include?(:focused) && @element.attribute(:focused)
         return BOLD if @element.size_of(:children).zero?
       end
       SOLID
@@ -128,8 +132,8 @@ class Accessibility::Graph
     # @return [String]
     attr_accessor :style
 
-    # @param [Accessibility::Graph::Node]
-    # @param [Accessibility::Graph::Node]
+    # @param head [Accessibility::Graph::Node]
+    # @param tail [Accessibility::Graph::Node]
     def initialize head, tail
       @head, @tail = head, tail
     end
@@ -155,7 +159,7 @@ class Accessibility::Graph
   # @return [Array<Accessibility::Graph::Edge>]
   attr_reader :edges
 
-  # @param [AX::Element]
+  # @param root [AX::Element]
   def initialize root
     root_node   = Node.new(root)
     @nodes      = [root_node]

data/lib/accessibility/{pp_inspector.rb → pretty_printer.rb}

@@ -10,13 +10,13 @@
 #  - `#attribute` returns the value of a given attribute
 #  - `#size_of` returns the size for an attribute
 #
-module Accessibility::PPInspector
+module Accessibility::PrettyPrinter
 
   ##
   # Create an identifier for the receiver by using various attributes
   # that should make it very easy to identify the element.
   #
-  # @return [String]
+  # @return [String,#to_s]
   def pp_identifier
     # @note use, or lack of use, of #inspect is intentional for visual effect
 
@@ -49,8 +49,7 @@ module Accessibility::PPInspector
       return " id=#{attribute(:identifier)}"
     end
 
-    # @todo should we have other fallbacks?
-    return EMPTY_STRING
+  rescue NoMethodError
   end
 
   ##
@@ -88,7 +87,7 @@ module Accessibility::PPInspector
   # is the given attribute, and the check box value will be
   # determined by the value of the attribute.
   #
-  # @param [Symbol]
+  # @param attr [Symbol]
   # @return [String]
   def pp_checkbox attr
     " #{attr}[#{attribute(attr) ? CHECKMARK : CROSS }]"

data/lib/accessibility/qualifier.rb

@@ -1,4 +1,6 @@
 # -*- coding: utf-8 -*-
+
+require 'active_support/core_ext/object/blank'
 require 'accessibility/translator'
 
 ##
@@ -22,21 +24,21 @@ class Accessibility::Qualifier
   #     element.children.size > 5 && NSContainsRect(element.bounds, rect)
   #   end
   #
-  # @param [#to_s]
-  # @param [Hash]
+  # @param klass [#to_s]
+  # @param criteria [Hash]
   # @yield Optional block that can qualify an element
   def initialize klass, criteria
     @klass    = TRANSLATOR.classify(klass)
     @criteria = criteria
     @block    = Proc.new if block_given?
-    compile criteria
+    compile!
   end
 
   ##
   # Whether or not a candidate object matches the criteria given
   # at initialization.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   def qualifies? element
     the_right_type?(element) && meets_criteria?(element)
   end
@@ -62,9 +64,9 @@ class Accessibility::Qualifier
   # array. This is done to avoid checking types for each call to
   # {#qualifies?}.
   #
-  # @param [Hash]
-  def compile criteria
-    @filters = criteria.map do |key, value|
+  # @param criteria [Hash]
+  def compile!
+    @filters = @criteria.map do |key, value|
       if value.kind_of? Hash
         [:subsearch, key, value]
       elsif key.kind_of? Array
@@ -84,7 +86,7 @@ class Accessibility::Qualifier
   # Checks if a candidate object is of the correct class, respecting
   # that that the class being searched for may not be defined yet.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   def the_right_type? element
     unless @const
       if AX.const_defined? @klass
@@ -100,7 +102,7 @@ class Accessibility::Qualifier
   # Determines if the element meets all the criteria of the filters,
   # spawning sub-searches if necessary.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   def meets_criteria? element
     @filters.all? do |filter|
       self.send *filter, element
@@ -112,19 +114,27 @@ class Accessibility::Qualifier
   end
 
   def match attr, regexp, element
-    element.attribute(attr).to_s.match regexp
+    if element.attributes.include? attr
+      element.attribute(attr).to_s.match regexp
+    end
   end
 
   def equality attr, value, element
-    element.attribute(attr) == value
+    if element.attributes.include? attr
+      element.attribute(attr) == value
+    end
   end
 
   def parameterized_match attr, param, regexp, element
-    element.parameterized_attribute(attr, param).to_s.match regexp
+    if element.parameterized_attributes.include? attr
+      element.parameterized_attribute(attr, param).to_s.match regexp
+    end
   end
 
   def parameterized_equality attr, param, value, element
-    element.parameterized_attribute(attr, param) == value
+    if element.parameterized_attributes.include? attr
+      element.parameterized_attribute(attr, param) == value
+    end
   end
 
   def block_check element

data/lib/accessibility/string.rb

@@ -26,9 +26,9 @@ module Accessibility::String
   # {Accessibility::String::EventGenerator::CUSTOM}.
   #
   # For more details on event generation, read the
-  # [Keyboarding documentation](http://github.com/Marketcircle/AXElements/wiki/Keyboarding).
+  # [Keyboarding wiki](http://github.com/Marketcircle/AXElements/wiki/Keyboarding).
   #
-  # @param [String]
+  # @param string [#to_s]
   # @return [Array<Array(Fixnum,Boolean)>]
   def keyboard_events_for string
     EventGenerator.new(Lexer.new(string).lex).generate
@@ -55,7 +55,7 @@ module Accessibility::String
     # @return [Array<String,Array<String,...>]
     attr_accessor :tokens
 
-    # @param [#to_s]
+    # @param string [#to_s]
     def initialize string
       @chars  = string.to_s
       @tokens = []
@@ -395,7 +395,7 @@ module Accessibility::String
     # @return [Array<Array(Fixnum,Boolean)>]
     attr_reader :events
 
-    # @param [Array<String,Array<String,Array...>>]
+    # @param tokens [Array<String,Array<String,Array...>>]
     def initialize tokens
       @tokens = tokens
       # *3 since the output array will be at least *2 the