AXElements 0.6.0beta1 → 0.6.0beta2

data/Rakefile

@@ -70,7 +70,7 @@ task :fixture do
 end
 
 require 'rake/testtask'
-Rake::TestTask.new(:test) do |t|
+Rake::TestTask.new do |t|
   t.libs     << 'test' << 'ext/key_coder'
   t.pattern   = 'test/**/test_*.rb'
   t.ruby_opts = ['-rhelper']

data/docs/Debugging.markdown

@@ -4,6 +4,27 @@ This document includes instructions on using AXElements' built in
 tools to help you debug issues with your scripts, or in cases where
 you might find a bug in AXElements itself or MacRuby.
 
+## Visibility
+
+Sometimes an object that should be visible to accessibility does not
+show up. Sometimes it will be invisible to the Accessibility Inspector
+and sometimes it will be invisible to AXElements. This is because the
+inspector uses hit testing to find objects and AXElements uses the
+`children` and `parent` attributes (usually). Depending on which part
+of the accessibility protocol is not being implemented correctly, one
+or both tools might fail to work.
+
+Fortunately, failures in the accessibility API are few and far
+between. The one big,
+[known issue](http://openradar.appspot.com/6832098) is with menu bar
+items; you cannot work around this issue without hacking into private
+Apple APIs. Specifically, you would need to override built in
+accessibility methods in the class that implement the user interface
+for NSStatusItem, which is a private class; or you could build your
+status bar item as an NSMenuExtra, which is another private class. You
+can find more tips on augmenting accessibility for apps in the
+{file:docs/AccessibilityTips.markdown Accessibility Tips} document.
+
 ## Trees
 
 Sometimes you need to see the big picture, the whole UI tree at
@@ -41,8 +62,6 @@ but the text tree dump method uses {Accessibility::DFEnumerator}.
 
 ### Dot Graph
 
-__NOTE__: This feature isn't actually done yet. Coming soon, I promise.
-
 For super fancy text trees, AXElements can generate dot graphs for
 consumption by [Graphviz](http://www.graphviz.org/). In this case, you
 want to call {Accessibility.graph} and pass the root of the tree you
@@ -62,8 +81,8 @@ AXElements was that you could not search through the menu bar causing
 a text dump to fail in a very difficult to trace manner.
 
 In these cases you will need to use your deductive reasoning to figure
-out where the problem is coming from. Fortunately, I have provided
-some tools to help you along the way.
+out where the problem is coming from. Fortunately, AXElements has some
+tools to help you along the way.
 
 ## All The Way Up
 

data/lib/AXElements.rb

@@ -0,0 +1 @@
+require 'ax_elements'

data/lib/ax_elements/accessibility.rb

@@ -31,7 +31,9 @@ class << Accessibility
   #
   # @return [String]
   def graph root
-    raise NotImplementedError, 'Please implement me, :('
+    dot = Graph.new(root)
+    dot.build!
+    dot.to_s
   end
 
   ##

data/lib/ax_elements/accessibility/graph.rb

@@ -0,0 +1,118 @@
+##
+# They see me graphing, they hatin, patrollin they can't catch me graphin' dirty.
+class Accessibility::Graph
+
+  ##
+  # 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.
+  #
+  # @return [Array<Accessibility::Graph::Node>]
+  attr_reader :edge_queue
+
+  ##
+  # List of nodes in the UI hierarchy.
+  #
+  # @return [Array<Accessibility::Graph::Node>]
+  attr_reader :nodes
+
+  ##
+  # A node in the UI hierarchy. Used by {Accessibility::Graph} in order
+  # to build Graphviz dot graphs.
+  class Node
+
+    # @return [AX::Element]
+    attr_reader :ref
+
+    ##
+    # Unique identifier for the node.
+    #
+    # @return [String]
+    attr_reader :id
+
+    ##
+    # Label to use for displaying the node.
+    #
+    # @return [String]
+    attr_reader :label
+
+    ##
+    # Shape to draw the node as.
+    #
+    # @return [String]
+    attr_reader :shape
+
+    ##
+    # Colour to fill the node with.
+    #
+    # @return [String]
+    attr_reader :colour
+
+    # @param [AX::Element]
+    def initialize element
+      @ref    = element
+      @id     = "element_#{element.object_id}"
+      @label  = element.class.to_s
+      @shape  = 3 # based on size?
+      @colour = 3 # rotate a la minitest?
+    end
+  end
+
+  ##
+  # List of edges in the graph.
+  #
+  # @return [Hash{Accessibility::Graph::Node=>Accessibility::Graph::Node}]
+  attr_reader :edges
+
+  # @param [AX::Element]
+  def initialize root
+    @nodes      = []
+    @edges      = {}
+    @edge_queue = [:root] # hack
+    add_node      root
+  end
+
+  ##
+  # Construct the list of nodes and edges for the graph...
+  def build!
+    Accessibility::BFEnumerator.new(nodes.first.ref).each do |element|
+      add_node element
+    end
+  end
+
+  ##
+  #
+  #
+  # @return [String]
+  def to_s
+    graph  = "digraph {\n"
+    graph << nodes_list
+    graph << edges_list
+    graph << "}\n"
+  end
+
+    def nodes_list
+      nodes.reduce('') do |string, node|
+        string << "#{node.name} [label=\"#{node.label}\"]\n"
+      end
+    end
+
+    def edges_list
+      edges.delete_if { |_,v| v == :root } # remove hack
+      edges.reduce('') do |string, pair|
+        string << "#{pair.second.name} -> #{pair.first.name}\n"
+      end
+    end
+
+    def add_node element
+      node   = Node.new(element)
+      nodes << node
+      edges[node] = edge_queue.shift
+      if element.respond_to? :children
+        element.size_of(:children).times do
+          edge_queue << node
+        end
+      end
+    end
+
+  end

data/lib/ax_elements/inspector.rb

@@ -37,7 +37,8 @@ module Accessibility::PPInspector
       if val.kind_of? NSString
         return " #{val.inspect}" unless val.empty?
       else
-        return " value=#{val.inspect}"
+        # we assume that nil is not a legitimate value
+        return " value=#{val.inspect}" unless val.nil?
       end
     end
 
@@ -71,7 +72,11 @@ module Accessibility::PPInspector
   # @return [String]
   def pp_position
     position = attribute :position
-    " (#{position.x}, #{position.y})"
+    if position
+      " (#{position.x}, #{position.y})"
+    else
+      ::EMPTY_STRING
+    end
   end
 
   ##

data/lib/ax_elements/version.rb

@@ -2,7 +2,7 @@
 
 module Accessibility
   # @return [String]
-  VERSION   = '0.6.0beta1'
+  VERSION   = '0.6.0beta2'
 
   # @return [String]
   CODE_NAME = 'Luxray'

data/test/test_inspector.rb

@@ -24,7 +24,10 @@ class TestPPInspector < MiniTest::Unit::TestCase
     assert_match /value=3.14/, pp_identifier
 
     @attribute  = ''
-    assert_match NSString.string, pp_identifier
+    assert_match ::EMPTY_STRING, pp_identifier
+
+    @attribute  = nil
+    assert_match ::EMPTY_STRING, pp_identifier
   end
 
   def test_identifier_using_title
@@ -73,6 +76,12 @@ class TestPPInspector < MiniTest::Unit::TestCase
     assert_match /\(3\.14, -5\.0\)/, pp_position
   end
 
+  # this sometimes happens, even though it shouldn't
+  def test_position_is_nil
+    @attribute = nil
+    assert_equal ::EMPTY_STRING, pp_position
+  end
+
   def test_children_pluralizes_properly
     @size_of = 2
     assert_match /2 children/, pp_children

metadata

@@ -2,14 +2,14 @@
 name: AXElements
 version: !ruby/object:Gem::Version
   prerelease: 5
-  version: 0.6.0beta1
+  version: 0.6.0beta2
 platform: ruby
 authors:
 - Mark Rada
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-29 00:00:00 -04:00
+date: 2011-10-02 00:00:00 -04:00
 default_executable: 
 dependencies:
 - !ruby/object:Gem::Dependency
@@ -123,6 +123,7 @@ extra_rdoc_files:
 - README.markdown
 files:
 - lib/ax_elements/accessibility/enumerators.rb
+- lib/ax_elements/accessibility/graph.rb
 - lib/ax_elements/accessibility/language.rb
 - lib/ax_elements/accessibility/qualifier.rb
 - lib/ax_elements/accessibility.rb
@@ -139,6 +140,7 @@ files:
 - lib/ax_elements/notification.rb
 - lib/ax_elements/version.rb
 - lib/ax_elements.rb
+- lib/AXElements.rb
 - lib/minitest/ax_elements.rb
 - lib/mouse.rb
 - lib/rspec/expectations/ax_elements.rb