AXElements 0.7.8 → 0.8.0

data/lib/accessibility/enumerators.rb

@@ -30,11 +30,12 @@ module Accessibility::Enumerators
     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.
+    # @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
+    #       built in implementation. 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
@@ -60,14 +61,14 @@ module Accessibility::Enumerators
       until stack.empty?
         current = stack.shift
         yield current
-        # needed to reverse it since child ordering seems to matter in practice
+        # needed to reverse, child ordering matters in practice
         stack.unshift *current.children
       end
     end
 
     ##
-    # Walk the UI element tree and yield both the element and the level
-    # that the element is at relative to the root.
+    # 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,AXUIElementRef]
     # @yieldparam [Number]

data/lib/accessibility/errors.rb

@@ -1,32 +1,31 @@
-require 'accessibility/debug'
-
 ##
 # 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}]
   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?
+    msg << "\nSubtree:\n\n" << subtree_for(searcher) if Accessibility.debug?
     super msg
   end
 
 
   private
 
+  # Nice string representation of what was being searched for
   def pp_searchee searchee, filters
     Accessibility::Qualifier.new(searchee, filters).describe
   end
 
+  # Nice string representation of element's path from the application root
   def path_to element
-    Accessibility::Debug.path(element).map! { |x| x.inspect }.join("\n\t")
-  end
-
-  def debug searcher
-    Accessibility::Debug.text_subtree(searcher)
+    element.ancestry.map! { |x| x.inspect }.join("\n\t")
   end
 
 end

data/lib/accessibility/factory.rb

@@ -9,13 +9,20 @@ module AX; 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 method and wraps it if
-  # needed. Meant for taking a return value from {Accessibility::Core#attr:for:}
-  # and friends.
+  # 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 `AXValue` into a `CGPoint` or an
-  # `AXUIElementRef` into some kind of {AX::Element} object.
+  # 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)
@@ -73,7 +80,7 @@ module Accessibility::Factory
         subrole = ref.subrole
         # Some objects claim to have a subrole but return nil
         if subrole
-          class_for(TRANSLATOR.unprefix(subrole), and: role).new ref
+          class_for2(TRANSLATOR.unprefix(subrole), role).new ref
         else
           class_for(role).new ref
         end
@@ -118,12 +125,12 @@ module Accessibility::Factory
   # @param [#to_s]
   # @param [#to_s]
   # @return [Class]
-  def class_for subrole, and: role
+  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
-      create_class subrole, with_superclass: role
+      create_class2 subrole, role
     end
   end
 
@@ -145,7 +152,7 @@ module Accessibility::Factory
   # @param [#to_s] name
   # @param [#to_s] superklass
   # @return [Class]
-  def create_class name, with_superclass: superklass
+  def create_class2 name, superklass
     unless AX.const_defined? superklass, false
       create_class superklass
     end

data/lib/accessibility/graph.rb

@@ -4,11 +4,13 @@
 # an image for the graph.
 #
 # You can learn more about generating graphs in the
-# {file:docs/Debugging.markdown Debugging} tutorial.
+# [Debugging tutorial](http://github.com/Marketcircle/AXElements/wiki/Debugging).
+#
+# [Learn more about GraphViz](http://www.graphviz.org/).
 class Accessibility::Graph
 
   ##
-  # @todo Graphs could be a lot nicer looking. That is, nodes could be much
+  # @todo Graphs could be 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
@@ -35,38 +37,82 @@ class Accessibility::Graph
 
     # @return [String]
     def to_dot
-      "#{@id} #{identifier} #{shape}"
+      "#{@id} #{identifier} [shape=#{shape}] [style=#{style}] [color=#{colour}]"
     end
 
 
     private
 
-    EMPTY_STRING = ''
-    NAMESPACE = '::'
-
     def identifier
       klass = @element.class.to_s.split(NAMESPACE).last
-      ident = @element.pp_identifier
+      ident = @element.pp_identifier.dup
+      if ident.length > 12
+        ident = "#{ident[0...12]}..."
+      end
+      ident << '"' if ident[1] == QUOTE && ident[-1] != QUOTE
       ident.gsub! /"/, '\"'
+      ident.gsub! /\\/, '\\'
       "[label = \"#{klass}#{ident}\"]"
     end
 
     def shape
-      @element.actions.empty? ? OVAL : BOX
+      (@element.attribute(:focused) && OCTAGON) ||
+      (@element.actions.empty? && OVAL)         ||
+      BOX
     end
 
-    def enabled
-      FILL if @element.enabled?
+    def style
+      # fill in the node if it is disabled (greyed out effect)
+      if @element.attributes.include?(:enabled)
+        return FILLED unless @element.attribute(:enabled)
+      end
+      # bold if focused and no children
+      if @element.attribute(:focused)
+        return BOLD if @element.size_of(:children).zero?
+      end
+      SOLID
     end
 
-    def focus
-      BOLD if @element.focused?
+    def colour
+      if @element.attributes.include?(:enabled)
+        return GREY unless @element.attribute(:enabled)
+      end
+      BLACK
     end
 
-    OVAL = '[shape = oval]'
-    BOX  = '[shape = box]'
-    BOLD = '[style = bold]'
-    FILL = '[style = filled] [color = "grey"]'
+    # @private
+    # @return [String]
+    EMPTY_STRING = ''
+    # @private
+    # @return [String]
+    NAMESPACE    = '::'
+    # @private
+    # @return [String]
+    QUOTE        = '"'
+    # @private
+    # @return [String]
+    OVAL         = 'oval'
+    # @private
+    # @return [String]
+    BOX          = 'box'
+    # @private
+    # @return [String]
+    OCTAGON      = 'doubleoctagon'
+    # @private
+    # @return [String]
+    BOLD         = 'bold'
+    # @private
+    # @return [String]
+    FILLED       = 'filled'
+    # @private
+    # @return [String]
+    SOLID        = 'solid'
+    # @private
+    # @return [String]
+    GREY         = 'grey'
+    # @private
+    # @return [String]
+    BLACK        = 'black'
   end
 
   ##
@@ -83,8 +129,7 @@ class Accessibility::Graph
     # @param [Accessibility::Graph::Node]
     # @param [Accessibility::Graph::Node]
     def initialize head, tail
-      @head = head
-      @tail = tail
+      @head, @tail = head, tail
     end
 
     # @return [String]
@@ -117,7 +162,7 @@ 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.
-    @edge_queue = Array.new(root.size_of(:children), root_node)
+    @edge_queue = Array.new(root.children.size, root_node)
   end
 
   ##
@@ -130,7 +175,8 @@ class Accessibility::Graph
     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)
+      # should use #size_of(:children), but that doesn't in all cases
+      @edge_queue.concat Array.new(element.children.size, node)
     end
   end
 
@@ -141,9 +187,9 @@ class Accessibility::Graph
   # @return [String]
   def to_dot
     graph  = "digraph {\n"
-    graph << nodes.map(&:to_dot).join("\n")
+    graph << nodes.map(&:to_dot).join(";\n")
     graph << "\n\n"
-    graph << edges.map(&:to_dot).join("\n")
+    graph << edges.map(&:to_dot).join(";\n")
     graph << "\n}\n"
   end
 

data/lib/accessibility/highlighter.rb

@@ -0,0 +1,86 @@
+framework 'AppKit'
+require   'accessibility/version'
+
+##
+# A screen highlighter for debugging. When you initialize a highligter
+# object it will highlight the given bounds on the screen.
+#
+# Highligter objects can have their colour configured at initialization,
+# and can also have a timeout to automatically stop displaying.
+#
+# @example
+#
+#   h = Accessibility::Highlighter.new(CGRectMake(100,100,100,100))
+#   # when you are done...
+#   h.stop
+#
+class Accessibility::Highlighter < NSWindow
+
+  # @param [CGRect]
+  # @param [Hash] opts
+  # @option opts [Number] :timeout
+  # @option opts [NSColor] :colour (NSColor.magentaColor)
+  def initialize bounds, opts = {}
+    colour = opts[:colour] || opts[:color] || NSColor.magentaColor
+
+    bounds.flip! # we assume the rect is in the other co-ordinate system
+
+    initWithContentRect bounds,
+             styleMask: NSBorderlessWindowMask,
+               backing: NSBackingStoreBuffered,
+                 defer: true
+    setOpaque false
+    setAlphaValue 0.20
+    setLevel NSStatusWindowLevel
+    setBackgroundColor colour
+    setIgnoresMouseEvents true
+    setFrame bounds, display: false
+    makeKeyAndOrderFront NSApp
+
+    if opts.has_key? :timeout
+      Dispatch::Queue.new(queue_id).after opts[:timeout] do
+        self.stop
+      end
+    end
+  end
+
+  ##
+  # Tell the highlighter to stop displaying.
+  #
+  # @return [self]
+  def stop
+    close
+  end
+
+
+  private
+
+  def queue_id
+    "com.marketcircle.axelements.window_killer_#{hash}"
+  end
+end
+
+
+##
+# AXElements extensions to `CGRect`.
+class CGRect
+  ##
+  # Treats the rect as belonging to one co-ordinate system and then
+  # converts it to the other system.
+  #
+  # This is useful because accessibility API's expect to work with
+  # the flipped co-ordinate system (origin in top left), but AppKit
+  # prefers to use the cartesian co-ordinate system (origin in bottom
+  # left).
+  #
+  # @return [CGRect]
+  def flip!
+    screen_height = NSMaxY(NSScreen.mainScreen.frame)
+    origin.y      = screen_height - NSMaxY(self)
+    self
+  end
+end
+
+
+# Initialize the shared application so that windows can be created
+NSApplication.sharedApplication

data/lib/accessibility/pp_inspector.rb

@@ -13,8 +13,8 @@
 module Accessibility::PPInspector
 
   ##
-  # Create an identifier for `self` using various attributes that should
-  # make it very easy to identify the element.
+  # Create an identifier for the receiver by using various attributes
+  # that should make it very easy to identify the element.
   #
   # @return [String]
   def pp_identifier
@@ -55,7 +55,7 @@ module Accessibility::PPInspector
 
   ##
   # Create a string that succinctly encodes the screen coordinates
-  # of `self`.
+  # of the receiver.
   #
   # @return [String]
   def pp_position
@@ -69,7 +69,7 @@ module Accessibility::PPInspector
 
   ##
   # Create a string that nicely presents the number of children
-  # that `self` has.
+  # that the receiver has.
   #
   # @return [String]
   def pp_children

data/lib/accessibility/qualifier.rb

@@ -10,7 +10,7 @@ class Accessibility::Qualifier
   # Initialize a qualifier with the kind of object that you want to
   # qualify and a dictionary of filter criteria. You can optionally
   # pass a block if your qualification criteria is too complicated
-  # for key/value pairs and the blocks return value will be used to
+  # for key/value pairs; the blocks return value will be used to
   # determine if an element qualifies.
   #
   # @example
@@ -22,7 +22,7 @@ class Accessibility::Qualifier
   #     element.children.size > 5 && NSContainsRect(element.bounds, rect)
   #   end
   #
-  # @param [#to_s] klass
+  # @param [#to_s]
   # @param [Hash]
   # @yield Optional block that can qualify an element
   def initialize klass, criteria
@@ -41,6 +41,10 @@ class Accessibility::Qualifier
     the_right_type?(element) && meets_criteria?(element)
   end
 
+  ##
+  # Return a compact description of the qualifier. If the qualifier
+  # includes a block then a checkmarked box will be included.
+  #
   # @return [String]
   def describe
     "#{@klass}#{@criteria.ax_pp}#{@block ? '[✔]' : ''}"
@@ -49,16 +53,14 @@ class Accessibility::Qualifier
 
   private
 
-  ##
   # @private
-  #
-  # Local reference to the {Accessibility::Translator}.
-  #
   # @return [Accessibility::Translator]
   TRANSLATOR = Accessibility::Translator.instance
 
   ##
   # Take a hash of search filters and generate an optimized search
+  # array. This is done to avoid checking types for each call to
+  # {#qualifies?}.
   #
   # @param [Hash]
   def compile criteria
@@ -118,11 +120,11 @@ class Accessibility::Qualifier
   end
 
   def parameterized_match attr, param, regexp, element
-    element.attribute(attr, for_parameter: param).to_s.match regexp
+    element.parameterized_attribute(attr, param).to_s.match regexp
   end
 
   def parameterized_equality attr, param, value, element
-    element.attribute(attr, for_parameter: param) == value
+    element.parameterized_attribute(attr, param) == value
   end
 
   def block_check element
@@ -133,7 +135,7 @@ end
 
 
 ##
-# Extensions to `NSDictionary`.
+# AXElements extensions to `NSDictionary`.
 class NSDictionary
   ##
   # Format the hash for AXElements pretty printing.

data/lib/accessibility/string.rb

@@ -26,7 +26,7 @@ module Accessibility::String
   # {Accessibility::String::EventGenerator::CUSTOM}.
   #
   # For more details on event generation, read the
-  # {file:docs/KeyboardEvents.markdown Keyboard Events} documentation.
+  # [Keyboarding documentation](http://github.com/Marketcircle/AXElements/wiki/Keyboarding).
   #
   # @param [String]
   # @return [Array<Array(Fixnum,Boolean)>]
@@ -43,7 +43,7 @@ module Accessibility::String
   # @example
   #
   #   Lexer.new("Hai").lex          # => ['H','a','i']
-  #   Lexer.new("\\CAPSLOCK").lex   # => [["\\CAPSLOCK"]]
+  #   Lexer.new("\\CONTROL").lex    # => [["\\CONTROL"]]
   #   Lexer.new("\\COMMAND+a").lex  # => [["\\COMMAND", ['a']]]
   #   Lexer.new("One\nTwo").lex     # => ['O','n','e',"\n",'T','w','o']
   #
@@ -132,10 +132,13 @@ module Accessibility::String
     end
 
     # @private
+    # @return [String]
     SPACE         = " "
     # @private
+    # @return [String]
     PLUS          = "+"
     # @private
+    # @return [String]
     CUSTOM_ESCAPE = "\\"
   end
 
@@ -150,8 +153,8 @@ module Accessibility::String
   #   # Upper case 'A'
   #   EventGenerator.new(["A"]).generate  # => [[56,true],[70,true],[70,false],[56,false]]
   #
-  #   # Press the caps lock button, turn it on
-  #   EventGenerator.new([["\\CAPS"]]).generate # => [[0x39,true],[0x39,false]]
+  #   # Press the volume up key
+  #   EventGenerator.new([["\\F12"]]).generate # => [[0x6F,true],[0x6F,false]]
   #
   #   # Hotkey, press and hold command key and then 'a', then release both
   #   EventGenerator.new([["\\CMD",["a"]]]).generate # => [[55,true],[70,true],[70,false],[55,false]]
@@ -470,14 +473,19 @@ module Accessibility::String
     end
 
     # @private
+    # @return [String]
     EMPTY_STRING = ""
     # @private
+    # @return [Array(Number,Boolean)]
     OPTION_DOWN  = [58,  true]
     # @private
+    # @return [Array(Number,Boolean)]
     OPTION_UP    = [58, false]
     # @private
+    # @return [Array(Number,Boolean)]
     SHIFT_DOWN   = [56,  true]
     # @private
+    # @return [Array(Number,Boolean)]
     SHIFT_UP     = [56, false]
   end
 

data/lib/accessibility/translator.rb

@@ -16,9 +16,16 @@ end
 
 ##
 # Maintain all the rules for transforming Cocoa constants into something
-# a little more Rubyish.
+# a little more Rubyish and taking the Rubyish symbols and translating
+# them back to Cocoa constants.
 class Accessibility::Translator
 
+  ##
+  # Get the singleton instance of the {Accessibility::Translator} class.
+  # This is meant to mimic the important functionality of the
+  # `Singleton` mix-in.
+  #
+  # @return [Accessibility::Translator]
   def self.instance
     @instance ||= new
   end
@@ -54,6 +61,14 @@ class Accessibility::Translator
     @unprefixes[key]
   end
 
+  ##
+  # Take an array of Cocoa accessibility constants and return an
+  # array of shortened Ruby symbols.
+  #
+  # @example
+  #
+  #   rubyize ["AXRole", "AXTitleUIElement"] # => [:role, :title_ui_element]
+  #
   # @return [Array<Symbol>]
   def rubyize keys
     keys.map { |x| @rubyisms[x] }
@@ -102,7 +117,9 @@ class Accessibility::Translator
 
   ##
   # Try to turn an arbitrary symbol into a notification constant, and
-  # then get the value of the constant.
+  # then get the value of the constant. If it cannot be turned into
+  # a notification constant then the original string parameter will
+  # be returned.
   #
   # @param [#to_s]
   # @return [String]
@@ -156,19 +173,11 @@ class Accessibility::Translator
     end
   end
 
-  ##
   # @private
-  #
-  # Cached for performance.
-  #
   # @return [String]
   EMPTY_STRING = ''
 
-  ##
   # @private
-  #
-  # Performance hack.
-  #
   # @return [String]
   QUESTION_MARK = '?'
 end

data/lib/accessibility/version.rb

@@ -1,6 +1,8 @@
+##
+# The main AXElements namespace.
 module Accessibility
   # @return [String]
-  VERSION   = '0.7.8'
+  VERSION   = '0.8.0'
 
   # @return [String]
   CODE_NAME = 'Clefairy'