AXElements 0.9.0 → 1.0.0.alpha

data/lib/accessibility/dsl.rb

@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 
-require 'active_support/core_ext/object/blank'
-
 require 'mouse'
 require 'ax/element'
 require 'ax/application'
@@ -10,8 +8,6 @@ require 'ax/scroll_area'
 require 'ax/menu'
 require 'accessibility'
 require 'accessibility/enumerators'
-require 'accessibility/highlighter'
-
 
 ##
 # DSL methods for AXElements.
@@ -133,7 +129,7 @@ module Accessibility::DSL
   #   The normal way to raise an exception.
   def raise *args
     arg = args.first
-    arg.kind_of?(AX::Element) ? arg.perform(:raise) : Kernel.raise(*args)
+    arg.kind_of?(AX::Element) ? arg.perform(:raise) : super(*args)
   end
 
   ##
@@ -251,7 +247,7 @@ module Accessibility::DSL
   # @param path [String,Regexp]
   # @return [Boolean]
   def select_menu_item app, *path
-    app.application.select_menu_item *path
+    app.select_menu_item *path
   end
 
   ##
@@ -274,7 +270,7 @@ module Accessibility::DSL
   # @param app [AX::Application]
   # @return [AX::Window]
   def show_preferences_window_for app
-    app.application.show_preferences_window
+    app.show_preferences_window
   end
 
   ##
@@ -312,31 +308,6 @@ module Accessibility::DSL
     element.ancestor(:menu).scroll_to element
   end
 
-  ##
-  # @note This is a hack to workaround an AXAPI deficiency
-  # @note This method may move or be renamed in the next release, though
-  #       it will not be removed
-  #
-  # Find a contextual menu that is open near the mouses current position
-  #
-  # This method assumes that it is being called in the block of a call to
-  # {#right_click}, and that the contextual menu is going to be very close
-  # to the mouse pointer.
-  #
-  # @return [AX::Menu,nil]
-  def contextual_menu
-    # CAST, just like high school trigonometry! :P
-    c, a, s, t = quads = Array.new(4) { Mouse.current_position }
-    c.x -= 10; c.y += 10
-    a.x += 10; a.y += 10
-    s.x += 10; s.y -= 10
-    t.x -= 10; t.y -= 10
-    elements = quads.map { |quad| element_at_point quad }
-    elements.uniq!
-    elements.map! { |el| el.kind_of?(AX::Menu) ? el : el.ancestor(:menu) }
-    elements.find { |element| element.present? }
-  end
-
 
   # @!group Polling
 
@@ -505,7 +476,7 @@ module Accessibility::DSL
   # @option opts [Number] :wait (0.2) in seconds
   def move_mouse_to arg, opts = {}
     duration = opts[:duration] || 0.2
-    if Accessibility.debug? && arg.kind_of?(AX::Element)
+    if Accessibility.debug? && arg.respond_to?(:bounds)
       highlight arg, timeout: duration, color: NSColor.orangeColor
     end
     Mouse.move_to arg.to_point, duration
@@ -555,27 +526,6 @@ module Accessibility::DSL
     sleep wait
   end
 
-  ##
-  # @todo Need to expose the units option? Would allow scrolling by pixel.
-  #
-  # Horizontally scrolls an arbitrary number of lines at the mouses current
-  # point on the screen
-  #
-  # Use a positive number to scroll left, and a negative number to scroll
-  # right.
-  #
-  # If the second argument is provided then the mouse will move to that
-  # point first; the argument must respond to `#to_point`.
-  #
-  # @param lines [Number]
-  # @param obj [#to_point]
-  # @param wait [Number]
-  def horizontal_scroll lines, obj = nil, wait = 0.1
-    move_mouse_to obj, wait: 0 if obj
-    Mouse.horizontal_scroll lines
-    sleep wait
-  end
-
   ##
   # Perform a regular click.
   #
@@ -600,30 +550,20 @@ module Accessibility::DSL
     move_mouse_to obj, wait: 0 if obj
     Mouse.click_down
     yield if block_given?
-  ensure
     Mouse.click_up
     sleep wait
   end
 
   ##
-  # Perform a right (a.k.a. secondary) click action.
+  # Perform a right (aka secondary) click action.
   #
   # If an argument is provided then the mouse will move to that point
   # first; the argument must respond to `#to_point`.
   #
-  # If a block is given, it will be yielded to between the click down
-  # and click up event. This behaviour is the same as passing a block
-  # to {DSL#click}.
-  #
-  # @yield Optionally take a block that is executed between click down
-  #        and click up events.
   # @param obj [#to_point]
   def right_click obj = nil, wait = 0.2
     move_mouse_to obj, wait: 0 if obj
-    Mouse.right_click_down
-    yield if block_given?
-  ensure
-    Mouse.right_click_up
+    Mouse.right_click
     sleep wait
   end
   alias_method :secondary_click, :right_click
@@ -641,110 +581,6 @@ module Accessibility::DSL
     sleep wait
   end
 
-  ##
-  # Perform a triple click action
-  #
-  # If an argument is provided then the mouse will move to that point
-  # first; the argument must respond to `#to_point`.
-  #
-  # @param obj [#to_point]
-  def triple_click obj = nil, wait = 0.2
-    move_mouse_to obj, wait: 0 if obj
-    Mouse.triple_click
-    sleep wait
-  end
-
-  ##
-  # Perform a swipe gesture in the given `direction`
-  #
-  # Valid directions are:
-  #
-  #   - `:up`
-  #   - `:down`
-  #   - `:left`
-  #   - `:right`
-  #
-  # An optional second argument can be provided. If the argument
-  # is provided then the mouse pointer will move to that point first.
-  #
-  # @example
-  #
-  #   swipe :left, safari.web_area
-  #
-  # @param direction [Symbol]
-  # @param obj [#to_point]
-  def swipe direction, obj = nil, wait = 0.2
-    move_mouse_to obj, wait: 0 if obj
-    Mouse.swipe direction
-    sleep wait
-  end
-
-  ##
-  # Perform a pinch gesture in the given `direction`
-  #
-  # You can optionally specify the `magnification` factor and
-  # `position` for the pinch event.
-  #*
-  # Available pinch directions are:
-  #
-  #   - `:zoom` or `:expand`
-  #   - `:unzoom` or `:contract`
-  #
-  # Magnification is a relative magnification setting. A zoom value of
-  # `1.0` means `1.0` more than the current zoom level. `2.0` would be
-  # `2.0` levels higher than the current zoom.
-  #
-  # You can also optionally specify an object/point on screen for the mouse
-  # pointer to be moved to before the gesture begins.
-  #
-  # @param direction [Symbol]
-  # @param magnification [Float]
-  # @param obj [#to_point]
-  def pinch direction, magnification = 1, obj = nil, wait = 0.2
-    move_mouse_to obj, wait: 0 if obj
-    Mouse.pinch direction, magnification
-    sleep wait
-  end
-
-  ##
-  # Perform a rotation gesture in the given `direction` the given `angle` degrees
-  #
-  # Possible directions are:
-  #
-  #   - `:cw`, ':clockwise`, ':clock_wise` to rotate in the clockwise
-  #     direction
-  #   - `:ccw`, ':counter_clockwise`, `:counter_clock_wise` to rotate in
-  #     the the counter clockwise direction
-  #
-  # The `angle` parameter is a number of degrees to rotate. There are 360
-  # degrees in a full rotation, as you would expect in Euclidian geometry.
-  #
-  # You can also optionally specify an object/point on screen for the mouse
-  # pointer to be moved to before the gesture begins. The movement will
-  # be instantaneous.
-  #
-  # @param direction [Symbol]
-  # @param angle [Float]
-  # @param obj [#to_point]
-  def rotate direction, angle, obj = nil, wait = 0.2
-    move_mouse_to obj, wait: 0 if obj
-    Mouse.rotate direction, angle
-    sleep wait
-  end
-
-  ##
-  # Perform a smart magnify (double tap on trackpad)
-  #
-  # You can optionally specify an object/point on the screen where to perform
-  # the smart magnification. The mouse will move to this point first
-  #
-  # @param obj [#to_point]
-  def smart_magnify obj = nil, wait = 0.2
-    move_mouse_to obj, wait: 0 if obj
-    Mouse.smart_magnify
-    sleep wait
-  end
-
 
   # @!group Debug Helpers
 
@@ -775,11 +611,29 @@ module Accessibility::DSL
   # @option opts [NSColor] :colour (NSColor.magentaColor)
   # @return [Accessibility::Highlighter]
   def highlight obj, opts = {}
+    require 'accessibility/highlighter'
     Accessibility::Highlighter.new obj.bounds, opts
   end
 
   ##
-  # @note This method is currently experimental
+  # @deprecated Use {AX::Element#inspect_subtree} instead.
+  #
+  # Get the dump of the subtree of children and descendants for the given
+  # element. Each generation down the tree will be indented another level,
+  # and each element will be inspected.
+  #
+  # @example
+  #
+  #   puts subtree app
+  #
+  # @param element [AX::Element]
+  # @return [String]
+  def subtree element
+    element.inspect_subtree
+  end
+  alias_method :subtree_for, :subtree
+
+  ##
   # @note You will need to have GraphViz command line tools installed
   #       in order for this to work.
   #
@@ -843,26 +697,16 @@ module Accessibility::DSL
   alias_method :capture_screen, :screenshot
 
   ##
-  # See (ScreenRecorder)[http://rdoc.info/gems/screen_recorder/frames]
-  # for details on the screen recording options
-  #
-  # @example
-  #
-  #   file = record do
-  #     run_tests
-  #   end
-  #   `open '#{file}'`
+  # See {Accessibility::ScreenRecorder.record} for details.
   #
   # @param file [String]
-  # @yield
-  # @yieldparam recorder [ScreenRecorder]
   # @return [String]
   def record file = nil, &block
-    require 'screen_recorder'
+    require 'accessibility/screen_recorder'
     if file
-      ScreenRecorder.record file, &block
+      Accessibility::ScreenRecorder.record file, &block
     else
-      ScreenRecorder.record &block
+      Accessibility::ScreenRecorder.record &block
     end
   end
 
@@ -881,7 +725,7 @@ module Accessibility::DSL
   # @param id [String]
   # @return [AX::Application,nil]
   def app_with_bundle_identifier id
-    AX::Application.new id
+    Accessibility.application_with_bundle_identifier id
   end
   alias_method :app_with_bundle_id, :app_with_bundle_identifier
   alias_method :launch,             :app_with_bundle_identifier

data/lib/accessibility/enumerators.rb

@@ -25,6 +25,7 @@ module Accessibility::Enumerators
         kids.each do |x| yield x end
         queue.concat kids
       end
+      []
     end
 
     ##

data/lib/accessibility/factory.rb

@@ -1,27 +1,92 @@
 require 'accessibility/core'
 require 'accessibility/translator'
+require 'accessibility/statistics'
 
 ##
 # Namespace container for all the accessibility objects.
 module AX; class Element; end end
 
 
-class << AX
+##
+# Extensions to {Accessibility::Element} for the high level abstraction.
+# These extensions only make sense in the context of the high level API
+# and it requires knowledge of both layers, 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
+
+  def to_element
+    STATS.increment :Factory
+    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
+          class_for2(TRANSLATOR.unprefix(subroll), roll).new self
+        else
+          class_for(roll).new self
+        end
+      else
+        class_for(roll).new self
+      end
+    else # failsafe in case object dies before we get the role
+      AX::Element.new self
+    end
+  end
+
+  def to_box type
+    STATS.increment :Unwrap
+    ptr = Pointer.new BOX_TYPES[type]
+    AXValueGetValue(self, type, ptr)
+    ptr.value.to_ruby
+  end
+
+
+  private
 
   ##
   # @private
   #
-  # Mutex to make sure we only create one class at a time.
+  # Reference to the singleton instance of the translator.
   #
-  # @return [Mutex]
-  MUTEX = Mutex.new
+  # @return [Accessibility::Translator]
+  TRANSLATOR = Accessibility::Translator.instance
 
   ##
   # @private
   #
-  # Find the class for a given role
+  # Serial queue to make sure we only create one class at a time.
   #
-  # If the class does not exist it will be created.
+  # @return [Dispatch::Queue]
+  CREATE_QUEUE = Dispatch::Queue.new 'com.marketcircle.axelements.create'
+
+  ##
+  # Find the class for a given role. If the class does not exist it will
+  # be created.
   #
   # @param role [#to_s]
   # @return [Class]
@@ -34,11 +99,8 @@ class << AX
   end
 
   ##
-  # @private
-  #
-  # Find the class for a given subrole and role
-  #
-  # If the class does not exist it will be created on demand.
+  # 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]
@@ -52,15 +114,13 @@ class << AX
   end
 
   ##
-  # @private
-  #
-  # Create a class in the {AX} namespace that has {AX::Element} as the
-  # superclass
+  # Create a new class in the {AX} namespace that has {AX::Element}
+  # as the superclass.
   #
   # @param name [#to_s]
   # @return [Class]
   def create_class name
-    MUTEX.synchronize do
+    CREATE_QUEUE.sync do
       # re-check now that we are in the critical section
       @klass = if AX.const_defined? name, false
                  AX.const_get name
@@ -73,10 +133,8 @@ class << AX
   end
 
   ##
-  # @private
-  #
   # Create a new class in the {AX} namesapce that has the given
-  # `superklass` as the superclass
+  # `superklass` as the superclass..
   #
   # @param name [#to_s]
   # @param superklass [#to_s]
@@ -85,7 +143,7 @@ class << AX
     unless AX.const_defined? superklass, false
       create_class superklass
     end
-    MUTEX.synchronize do
+    CREATE_QUEUE.sync do
       # re-check now that we are in the critical section
       @klass = if AX.const_defined? name, false
                  AX.const_get name
@@ -98,117 +156,3 @@ class << AX
   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