AXElements 0.6.0beta2 → 0.7.5

data/lib/accessibility/enumerators.rb

@@ -0,0 +1,104 @@
+##
+# Namespace for enumerators used to navigate accessibility hierarchies.
+module Accessibility::Enumerators
+
+  ##
+  # Enumerator for visiting each element in a UI hierarchy in breadth
+  # first order.
+  class BreadthFirst
+    include Enumerable
+
+    # @param [AX::Element]
+    def initialize root
+      @root = root
+    end
+
+    ##
+    # Semi-lazily iterate through the tree.
+    #
+    # @yieldparam [AX::Element]
+    def each
+      # @todo Lazy-wrap element refs, might make things a bit faster
+      #       for fat trees; what is impact on thin trees?
+      # @todo See if we can implement the method in a single loop
+      queue = [@root]
+      until queue.empty?
+        queue.shift.attribute(:children).each do |x|
+          queue << x if x.attributes.include? :children
+          yield x
+        end
+      end
+    end
+
+    ##
+    # @note Explicitly defined so that escaping at the first found element
+    #       actually works. Since only a single `break` is called when an
+    #       item is found it does not fully escape the method. Technically,
+    #       we need to do this with other 'escape-early' iteraters, but
+    #       they aren't being used...yet.
+    #
+    # Override `Enumerable#find` for performance reasons.
+    def find
+      each { |x| return x if yield x }
+    end
+
+  end
+
+  ##
+  # Enumerator for visitng each element in a UI hierarchy in
+  # depth first order.
+  class DepthFirst
+    include Enumerable
+
+    # @param [AX::Element]
+    def initialize root
+      @root = root
+    end
+
+    # @yieldparam [AX::Element]
+    def each
+      stack = @root.attribute(:children)
+      until stack.empty?
+        current = stack.shift
+        yield current
+        if current.attributes.include? :children
+          # need to reverse it since child ordering seems to matter in practice
+          stack.unshift *current.attribute(:children)
+        end
+      end
+    end
+
+    ##
+    # Walk the UI element tree and yield both the element and the level
+    # that the element is at relative to the root.
+    #
+    # @yieldparam [AX::Element]
+    # @yieldparam [Number]
+    def each_with_level &block
+      # @todo A bit of a hack that I would like to fix one day...
+      @root.attribute(:children).each do |element|
+        recursive_each_with_level element, 1, block
+      end
+    end
+
+
+    private
+
+    ##
+    # Recursive implementation of a depth first iterator.
+    #
+    # @param [AX::Element]
+    # @param [Number]
+    # @param [#call]
+    def recursive_each_with_level element, depth, block
+      block.call element, depth
+      if element.respond_to? :children
+        element.attribute(:children).each do |x|
+          recursive_each_with_level x, depth + 1, block
+        end
+      end
+    end
+
+  end
+
+end

data/lib/accessibility/errors.rb

@@ -0,0 +1,32 @@
+require 'accessibility/debug'
+
+##
+# Error raised when an implicit search fails to return a result.
+class Accessibility::SearchFailure < NoMethodError
+
+  def initialize searcher, searchee, filters
+    filters = {} unless filters.kind_of? Hash
+    msg  = "Could not find `#{pp_searchee searchee, filters}` "
+    msg << "as a child of #{searcher.class}\n"
+    msg << "Element Path:\n\t" << path_to(searcher)
+    # @todo Consider turning this on by default
+    msg << "\nSubtree:\n\t" << debug(searcher) if Accessibility::Debug.on?
+    super msg
+  end
+
+
+  private
+
+  def pp_searchee searchee, filters
+    Accessibility::Qualifier.new(searchee, filters).describe
+  end
+
+  def path_to element
+    Accessibility::Debug.path(element).map! { |x| x.inspect }.join("\n\t")
+  end
+
+  def debug searcher
+    Accessibility::Debug.text_subtree(searcher)
+  end
+
+end

data/lib/accessibility/factory.rb

@@ -0,0 +1,153 @@
+require 'accessibility/core'
+require 'accessibility/translator'
+
+##
+# Namespace container for all the accessibility objects.
+module AX; end
+
+##
+# Mixin made for processing low level data from AXAPI methods.
+module Accessibility::Factory
+
+  ##
+  # Processes any given data from an AXAPI method and wraps it if
+  # needed. Meant for taking a return value from {Accessibility::Core#attr:for:}
+  # and friends.
+  #
+  # Generally, used to process an `AXValue` into a `CGPoint` or an
+  # `AXUIElementRef` into some kind of {AX::Element} object.
+  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
+
+  ##
+  # @private
+  #
+  # Reference to the singleton instance of the translator.
+  #
+  # @return [Accessibility::Translator]
+  TRANSLATOR = Accessibility::Translator.instance
+
+  ##
+  # @private
+  #
+  # Type ID for `AXUIElementRef` objects.
+  #
+  # @return [Number]
+  REF_TYPE   = AXUIElementGetTypeID()
+
+  ##
+  # @private
+  #
+  # Type ID for `CFArrayRef` objects.
+  #
+  # @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
+    role  = TRANSLATOR.unprefix ref.role
+    attrs = ref.attributes
+    klass = if attrs.include? KAXSubroleAttribute
+              subrole = ref.subrole
+              # Some objects claim to have a subrole but return nil
+              if subrole
+                class_for TRANSLATOR.unprefix(subrole), and: role
+              else
+                class_for role
+              end
+            else
+              class_for role
+            end
+    klass.new ref
+  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]
+  # @return [Class]
+  def class_for role
+    if AX.const_defined? role, false
+      AX.const_get role
+    else
+      create_class role
+    end
+  end
+
+  ##
+  # Find the class for a given subrole and role. If the class does not
+  # exist it will be created on demand.
+  #
+  # @param [#to_s]
+  # @param [#to_s]
+  # @return [Class]
+  def class_for subrole, and: 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
+      create_class subrole, with_superclass: role
+    end
+  end
+
+  ##
+  # Create a new class in the {AX} namespace that has {AX::Element}
+  # as the superclass.
+  #
+  # @param [#to_s]
+  # @return [Class]
+  def create_class name
+    klass = Class.new AX::Element
+    AX.const_set name, klass
+  end
+
+  ##
+  # Create a new class in the {AX} namesapce that has the given
+  # `superklass` as the superclass..
+  #
+  # @param [#to_s] name
+  # @param [#to_s] superklass
+  # @return [Class]
+  def create_class name, with_superclass: superklass
+    unless AX.const_defined? superklass, false
+      create_class superklass
+    end
+    klass = Class.new AX.const_get(superklass)
+    AX.const_set name, klass
+  end
+
+end

data/lib/accessibility/graph.rb

@@ -0,0 +1,150 @@
+##
+# DOT graph generator for AXElements. It can generate the digraph code
+# for a UI subtree. That code can then be given to GraphViz to generate
+# an image for the graph.
+#
+# You can learn more about generating graphs in the
+# {file:docs/Debugging.markdown Debugging} tutorial.
+class Accessibility::Graph
+
+  ##
+  # @todo Graphs could be a lot nicer looking. That is, nodes could be much
+  #       more easily identifiable, by allowing different classes to tell
+  #       the node more about itself. A mixin module/protocol should
+  #       probably be created, just as with the inspector mixin, and added
+  #       to abstract base and overridden as needed in subclasses. In this
+  #       way, an object can be more specific about what shape it is, how
+  #       it is coloured, etc.
+  #       Reference: http://www.graphviz.org/doc/info/attrs.html
+  #
+  # A node in the UI hierarchy. Used by {Accessibility::Graph} in order
+  # to build Graphviz DOT graphs.
+  class Node
+
+    # @return [String]
+    attr_reader :id
+
+    # @return [AX::Element]
+    attr_reader :element
+
+    # @param [AX::Element]
+    def initialize element
+      @element = element
+      @id      = "element_#{element.object_id}"
+    end
+
+    # @return [String]
+    def to_dot
+      "#{@id} #{identifier} #{shape}"
+    end
+
+
+    private
+
+    EMPTY_STRING = ''
+    NAMESPACE = '::'
+
+    def identifier
+      klass = @element.class.to_s.split(NAMESPACE).last
+      ident = @element.pp_identifier
+      ident.gsub! /"/, '\"'
+      "[label = \"#{klass}#{ident}\"]"
+    end
+
+    def shape
+      @element.actions.empty? ? OVAL : BOX
+    end
+
+    def enabled
+      FILL if @element.respond_to?(:enabled) && !@element.enabled?
+    end
+
+    def focus
+      BOLD if @element.respond_to?(:focused) && @element.focused?
+    end
+
+    OVAL = '[shape = oval]'
+    BOX  = '[shape = box]'
+    BOLD = '[style = bold]'
+    FILL = '[style = filled] [color = "grey"]'
+  end
+
+  ##
+  # An edge in the UI hierarchy. Used by {Accessibility::Graph} in order
+  # to build Graphviz DOT graphs.
+  class Edge
+
+    ##
+    # The style of arrowhead to use
+    #
+    # @return [String]
+    attr_accessor :style
+
+    # @param [Accessibility::Graph::Node]
+    # @param [Accessibility::Graph::Node]
+    def initialize head, tail
+      @head = head
+      @tail = tail
+    end
+
+    # @return [String]
+    def to_dot
+      arrow = style ? style : 'normal'
+      "#{@head.id} -> #{@tail.id} [arrowhead = #{arrow}]"
+    end
+
+  end
+
+
+  ##
+  # List of nodes in the UI hierarchy.
+  #
+  # @return [Array<Accessibility::Graph::Node>]
+  attr_reader :nodes
+
+  ##
+  # List of edges in the graph.
+  #
+  # @return [Array<Accessibility::Graph::Edge>]
+  attr_reader :edges
+
+  # @param [AX::Element]
+  def initialize root
+    root_node   = Node.new(root)
+    @nodes      = [root_node]
+    @edges      = []
+
+    # exploit the ordering of a breadth-first enumeration to simplify
+    # the creation of edges for the graph. This only works because
+    # the UI hiearchy is a simple tree.
+    @edge_queue = Array.new(root.size_of(:children), root_node)
+  end
+
+  ##
+  # Construct the list of nodes and edges for the graph.
+  #
+  # The secret sauce is that we create an edge queue to exploit the
+  # breadth first ordering of the enumerator, which makes building the
+  # edges very easy.
+  def build!
+    Accessibility::Enumerators::BreadthFirst.new(nodes.last.element).each do |element|
+      nodes << node = Node.new(element)
+      edges << Edge.new(node, @edge_queue.shift)
+      @edge_queue.concat Array.new(element.size_of(:children), node)
+    end
+  end
+
+  ##
+  # Generate the `dot` graph code. You should take this string and
+  # feed it to the `dot` program to have it generate the graph.
+  #
+  # @return [String]
+  def to_dot
+    graph  = "digraph {\n"
+    graph << nodes.map(&:to_dot).join("\n")
+    graph << "\n\n"
+    graph << edges.map(&:to_dot).join("\n")
+    graph << "\n}\n"
+  end
+
+end

data/lib/{ax_elements/inspector.rb → accessibility/pp_inspector.rb}

@@ -12,27 +12,16 @@
 #
 module Accessibility::PPInspector
 
-
-  protected
-
-  ##
-  # Added for backwards compatability with Snow Leopard.
-  #
-  # @return [String]
-  KAXIdentifierAttribute = 'AXIdentifier'.freeze
-
   ##
-  # @todo I feel a bit bad about having such a large method that has
-  #       some inefficiencies.
-  #
   # Create an identifier for `self` using various attributes that should
   # make it very easy to identify the element.
   #
   # @return [String]
   def pp_identifier
-    # use or lack of use of #inspect is intentional for visual effect
+    # @todo Break this method up into chunks
+    # @note use, or lack of use, of #inspect is intentional for visual effect
 
-    if attributes.include? KAXValueAttribute
+    if attributes.include? :value
       val = attribute :value
       if val.kind_of? NSString
         return " #{val.inspect}" unless val.empty?
@@ -42,27 +31,27 @@ module Accessibility::PPInspector
       end
     end
 
-    if attributes.include? KAXTitleAttribute
+    if attributes.include? :title
       val = attribute(:title)
       return " #{val.inspect}" if val && !val.empty?
     end
 
-    if attributes.include? KAXTitleUIElementAttribute
+    if attributes.include? :title_ui_element
       val = attribute :title_ui_element
-      return BUFFER + val.inspect if val
+      return " #{val.inspect}" if val
     end
 
-    if attributes.include? KAXDescriptionAttribute
+    if attributes.include? :description
       val = attribute(:description).to_s
-      return BUFFER + val unless val.empty?
+      return " #{val}" unless val.empty?
     end
 
-    if attributes.include? KAXIdentifierAttribute
+    if attributes.include? :identifier
       return " id=#{attribute(:identifier)}"
     end
 
     # @todo should we have other fallbacks?
-    return ::EMPTY_STRING
+    return EMPTY_STRING
   end
 
   ##
@@ -75,7 +64,7 @@ module Accessibility::PPInspector
     if position
       " (#{position.x}, #{position.y})"
     else
-      ::EMPTY_STRING
+      EMPTY_STRING
     end
   end
 
@@ -89,9 +78,9 @@ module Accessibility::PPInspector
     if child_count > 1
       " #{child_count} children"
     elsif child_count == 1
-      ' 1 child'
+      ONE_CHILD
     else # there are some odd edge cases
-      ::EMPTY_STRING
+      EMPTY_STRING
     end
   end
 
@@ -103,7 +92,7 @@ module Accessibility::PPInspector
   # @param [Symbol]
   # @return [String]
   def pp_checkbox attr
-    " #{attr}[#{attribute(attr) ? '✔' : '✘'}]"
+    " #{attr}[#{attribute(attr) ? CHECKMARK : CROSS }]"
   end
 
 
@@ -112,10 +101,32 @@ module Accessibility::PPInspector
   ##
   # @private
   #
-  # A string with a single space, used as a buffer. This is a
-  # performance hack.
+  # Constant string used by {#pp_checkbox}.
+  #
+  # @return [String]
+  CHECKMARK = '✔'
+
+  ##
+  # @private
+  #
+  # Constant string used by {#pp_checkbox}.
+  #
+  # @return [String]
+  CROSS = '✘'
+
+  ##
+  # @private
+  #
+  # Constant string used by {#pp_children}.
   #
   # @return [String]
-  BUFFER = ' '.freeze
+  ONE_CHILD = ' 1 child'
 
+  ##
+  # @private
+  #
+  # Constant used all over the place.
+  #
+  # @return [String]
+  EMPTY_STRING = ''
 end