AXElements 0.8.1 → 0.9.0

data/lib/accessibility/dsl.rb

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+require 'active_support/core_ext/object/blank'
+
 require 'mouse'
 require 'ax/element'
 require 'ax/application'
@@ -8,6 +10,8 @@ require 'ax/scroll_area'
 require 'ax/menu'
 require 'accessibility'
 require 'accessibility/enumerators'
+require 'accessibility/highlighter'
+
 
 ##
 # DSL methods for AXElements.
@@ -22,14 +26,14 @@ require 'accessibility/enumerators'
 module Accessibility::DSL
 
 
-  # @group Actions
+  # @!group Actions
 
   ##
   # We assume that any method that has the first argument with a type
   # of {AX::Element} is intended to be an action and so `#method_missing`
   # will forward the message to the element.
   #
-  # @param [String] method an action constant
+  # @param meth [String] an action constant
   def method_missing meth, *args
     arg = args.first
     if arg.kind_of? AX::Element
@@ -46,7 +50,7 @@ module Accessibility::DSL
   ##
   # Try to perform the `press` action on the given element.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   # @return [Boolean]
   def press element
     element.perform :press
@@ -55,7 +59,7 @@ module Accessibility::DSL
   ##
   # Try to perform the `show_menu` action on the given element.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   # @return [Boolean]
   def show_menu element
     element.perform :show_menu
@@ -64,7 +68,7 @@ module Accessibility::DSL
   ##
   # Try to perform the `pick` action on the given element.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   # @return [Boolean]
   def pick element
     element.perform :pick
@@ -73,7 +77,7 @@ module Accessibility::DSL
   ##
   # Try to perform the `decrement` action on the given element.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   # @return [Boolean]
   def decrement element
     element.perform :decrement
@@ -82,7 +86,7 @@ module Accessibility::DSL
   ##
   # Try to perform the `confirm` action on the given element.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   # @return [Boolean]
   def confirm element
     element.perform :confirm
@@ -91,7 +95,7 @@ module Accessibility::DSL
   ##
   # Try to perform the `increment` action on the given element.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   # @return [Boolean]
   def increment element
     element.perform :increment
@@ -100,7 +104,7 @@ module Accessibility::DSL
   ##
   # Try to perform the `delete` action on the given element.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   # @return [Boolean]
   def delete element
     element.perform :delete
@@ -109,7 +113,7 @@ module Accessibility::DSL
   ##
   # Try to perform the `cancel` action on the given element.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   # @return [Boolean]
   def cancel element
     element.perform :cancel
@@ -122,20 +126,20 @@ module Accessibility::DSL
   # Try to perform the `raise` action on the given element.
   #
   # @overload raise element
-  #   @param [AX::Element] element
+  #   @param element [AX::Element]
   #   @return [Boolean]
   #
   # @overload raise exception[, message[, backtrace]]
   #   The normal way to raise an exception.
   def raise *args
     arg = args.first
-    arg.kind_of?(AX::Element) ? arg.perform(:raise) : super(*args)
+    arg.kind_of?(AX::Element) ? arg.perform(:raise) : Kernel.raise(*args)
   end
 
   ##
   # Tell an app to hide itself.
   #
-  # @param [AX::Application]
+  # @param app [AX::Application]
   # @return [Boolean]
   def hide app
     app.perform :hide
@@ -144,7 +148,7 @@ module Accessibility::DSL
   ##
   # Tell an app to unhide itself.
   #
-  # @param [AX::Application]
+  # @param app [AX::Application]
   # @return [Boolean]
   def unhide app
     app.perform :unhide
@@ -154,7 +158,7 @@ module Accessibility::DSL
   ##
   # Tell an app to quit.
   #
-  # @param [AX::Application]
+  # @param app [AX::Application]
   # @return [Boolean]
   def terminate app
     app.perform :terminate
@@ -165,7 +169,7 @@ module Accessibility::DSL
   # focused. It is safe to pass any element into this method as nothing
   # will happen if it does not have a writable focused state attribute.
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   def set_focus_to element
     element.set(:focused, true) if element.writable? :focused
   end
@@ -180,8 +184,8 @@ module Accessibility::DSL
   #
   # @overload set element, attribute_name: new_value
   #   Set a specified attribute to a new value
-  #   @param [AX::Element] element
-  #   @param [Hash{attribute_name=>new_value}] change
+  #   @param element [AX::Element]
+  #   @param change [Hash{attribute_name=>new_value}]
   #
   # @example
   #
@@ -189,8 +193,8 @@ module Accessibility::DSL
   #
   # @overload set element, new_value
   #   Set the `value` attribute to a new value
-  #   @param [AX::Element] element
-  #   @param [Object] change
+  #   @param element [AX::Element]
+  #   @param change [Object]
   #
   # @example
   #
@@ -216,7 +220,7 @@ module Accessibility::DSL
   #
   # @overload type string
   #   Send input to the currently focused application
-  #   @param [#to_s]
+  #   @param string [String]
   #
   # @example
   #
@@ -224,7 +228,7 @@ module Accessibility::DSL
   #
   # @overload type string, app
   #   Send input to a specific application
-  #   @param [#to_s]
+  #   @param String [String]
   #   @param [AX::Application]
   #
   def type string, app = system_wide
@@ -243,18 +247,18 @@ module Accessibility::DSL
   #   select_menu_item mail, 'View', 'Sort By', 'Subject'
   #   select_menu_item mail, 'Edit', /Spelling/, /show spelling/i
   #
-  # @param [AX::Application]
-  # @param [String,Regexp] path
+  # @param app [AX::Application]
+  # @param path [String,Regexp]
   # @return [Boolean]
   def select_menu_item app, *path
-    app.select_menu_item *path
+    app.application.select_menu_item *path
   end
 
   ##
   # Show the "About" window for an app. Returns the window that is
   # opened.
   #
-  # @param [AX::Application]
+  # @param app [AX::Application]
   # @return [AX::Window]
   def show_about_window_for app
     app.show_about_window
@@ -267,10 +271,10 @@ module Accessibility::DSL
   # Try to open the preferences for an app. Returns the window that
   # is opened.
   #
-  # @param [AX::Application]
+  # @param app [AX::Application]
   # @return [AX::Window]
   def show_preferences_window_for app
-    app.show_preferences_window
+    app.application.show_preferences_window
   end
 
   ##
@@ -285,7 +289,7 @@ module Accessibility::DSL
   #
   #   scroll_to table.rows.last
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   # @return [void]
   def scroll_to element
     element.ancestor(:scroll_area).scroll_to element
@@ -302,14 +306,39 @@ module Accessibility::DSL
   #     scroll_menu_to pop_up.menu.item(title: "Expensive Cake")
   #   end
   #
-  # @param [AX:]
+  # @param element [AX::Element]
   # @return [void]
   def scroll_menu_to element
-    menu = element.ancestor(:menu).scroll_to element
+    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
+  # @!group Polling
 
   ##
   # Simply wait around for something to show up. This method is similar
@@ -335,11 +364,12 @@ module Accessibility::DSL
   #   # Waiting for something that will never show up
   #   wait_for :a_million_dollars, ancestor: fruit_basket, timeout: 1000000
   #
-  # @param [#to_s]
-  # @param [Hash] filters
+  # @param element [#to_s]
+  # @param filters [Hash]
   # @option filters [Number] :timeout (5) timeout in seconds
   # @option filters [AX::Element] :parent
   # @option filters [AX::Element] :ancestor
+  # @yield Optional block used as a search filter
   # @return [AX::Element,nil]
   def wait_for element, filters = {}, &block
     if filters.has_key? :ancestor
@@ -358,9 +388,9 @@ module Accessibility::DSL
   #
   # See {#wait_for} for more details.
   #
-  # @param [#to_s]
-  # @param [AX::Element]
-  # @param [Hash]
+  # @param descendant [#to_s]
+  # @param ancestor [AX::Element]
+  # @param filters [Hash]
   # @return [AX::Element,nil]
   def wait_for_descendant descendant, ancestor, filters, &block
     timeout = filters.delete(:timeout) || 5
@@ -388,9 +418,9 @@ module Accessibility::DSL
   #
   # See {#wait_for} for more details.
   #
-  # @param [#to_s]
-  # @param [AX::Element]
-  # @param [Hash]
+  # @param child [#to_s]
+  # @param parent [AX::Element]
+  # @param filters [Hash]
   # @return [AX::Element,nil]
   def wait_for_child child, parent, filters, &block
     timeout = filters.delete(:timeout) || 5
@@ -418,8 +448,8 @@ module Accessibility::DSL
   # all search results have been returned.
   #
   # @overload wait_for_invalidation_of element
-  # @param [AX::Element]
-  # @param [Hash] filters
+  # @param element [AX::Element]
+  # @param filters [Hash]
   # @option filters [Number] :timeout (5) in seconds
   # @return [Boolean]
   #
@@ -428,8 +458,8 @@ module Accessibility::DSL
   #   wait_for_invalidation_of table.row(static_text: { value: 'Cake' })
   #
   # @overload wait_for_invalidation_of kind, filters = {}, &block
-  # @param [#to_s]
-  # @param [Hash] filters
+  # @param element [#to_s]
+  # @param filters [Hash]
   # @option filters [Number] :timeout (5) in seconds
   # @return [Boolean]
   #
@@ -458,7 +488,7 @@ module Accessibility::DSL
   alias_method :wait_for_invalid,      :wait_for_invalidation_of
 
 
-  # @group Mouse Manipulation
+  # @!group Mouse Manipulation
 
   ##
   # Move the mouse cursor to the given point or object on the screen.
@@ -469,13 +499,13 @@ module Accessibility::DSL
   #  move_mouse_to [344, 516]
   #  move_mouse_to CGPoint.new(100, 100)
   #
-  # @param [#to_point]
-  # @param [Hash] opts
+  # @param arg [#to_point]
+  # @param opts [Hash]
   # @option opts [Number] :duration (0.2) in seconds
   # @option opts [Number] :wait (0.2) in seconds
   def move_mouse_to arg, opts = {}
     duration = opts[:duration] || 0.2
-    if Accessibility.debug? && arg.respond_to?(:bounds)
+    if Accessibility.debug? && arg.kind_of?(AX::Element)
       highlight arg, timeout: duration, color: NSColor.orangeColor
     end
     Mouse.move_to arg.to_point, duration
@@ -495,8 +525,8 @@ module Accessibility::DSL
   #   drag_mouse_to [100,100]
   #   drag_mouse_to drop_zone, from: desktop_icon
   #
-  # @param [#to_point]
-  # @param [Hash] opts
+  # @param arg [#to_point]
+  # @param opts [Hash]
   # @option opts [#to_point] :from a point to move to before dragging
   # @option opts [Number] :duration (0.2) in seconds
   # @option opts [Number] :wait (0.2) in seconds
@@ -516,14 +546,36 @@ module Accessibility::DSL
   # If the second argument is provided then the mouse will move to that
   # point first; the argument must respond to `#to_point`.
   #
-  # @param [Number]
-  # @param [#to_point]
+  # @param lines [Number]
+  # @param obj [#to_point]
+  # @param wait [Number]
   def scroll lines, obj = nil, wait = 0.1
     move_mouse_to obj, wait: 0 if obj
     Mouse.scroll lines
     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.
   #
@@ -543,25 +595,35 @@ module Accessibility::DSL
   #
   # @yield Optionally take a block that is executed between click down
   #        and click up events.
-  # @param [#to_point]
+  # @param obj [#to_point]
   def click obj = nil, wait = 0.2
     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 (aka secondary) click action.
+  # Perform a right (a.k.a. secondary) click action.
   #
   # If an argument is provided then the mouse will move to that point
   # first; the argument must respond to `#to_point`.
   #
-  # @param [#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
+    Mouse.right_click_down
+    yield if block_given?
+  ensure
+    Mouse.right_click_up
     sleep wait
   end
   alias_method :secondary_click, :right_click
@@ -572,15 +634,119 @@ module Accessibility::DSL
   # If an argument is provided then the mouse will move to that point
   # first; the argument must respond to `#to_point`.
   #
-  # @param [#to_point]
+  # @param obj [#to_point]
   def double_click obj = nil, wait = 0.2
     move_mouse_to obj, wait: 0 if obj
     Mouse.double_click
     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
 
-  # @group Debug Helpers
+  ##
+  # 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
 
   ##
   # Highlight an element on screen. You can optionally specify the
@@ -603,32 +769,17 @@ module Accessibility::DSL
   #   # highlighter automatically turns off after 5 seconds
   #   highlight window.outline.row, colour: NSColor.greenColor, timeout: 5
   #
-  # @param [#bounds]
-  # @param [Hash] opts
+  # @param obj [#bounds]
+  # @param opts [Hash]
   # @option opts [Number] :timeout
   # @option opts [NSColor] :colour (NSColor.magentaColor)
   # @return [Accessibility::Highlighter]
   def highlight obj, opts = {}
-    require 'accessibility/highlighter'
     Accessibility::Highlighter.new obj.bounds, opts
   end
 
   ##
-  # 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
-  #
-  # @return [String]
-  def subtree element
-    element.inspect_subtree
-  end
-  alias_method :subtree_for, :subtree
-
-  ##
+  # @note This method is currently experimental
   # @note You will need to have GraphViz command line tools installed
   #       in order for this to work.
   #
@@ -639,7 +790,7 @@ module Accessibility::DSL
   #
   #   graph app.main_window
   #
-  # @param [AX::Element]
+  # @param element [AX::Element]
   # @return [String] path to the saved image
   def graph element
     require 'accessibility/graph'
@@ -667,8 +818,8 @@ module Accessibility::DSL
   #   screenshot app.title, "/Volumes/SecretStash"
   #     # => "/Volumes/SecretStash/Safari-20120422184650.png"
   #
-  # @param [#to_s]
-  # @param [#to_s]
+  # @param name [#to_s]
+  # @param dir [#to_s]
   # @return [String] path to the screenshot
   def screenshot name = "AXElements-ScreenShot", dir = '~/Desktop'
     # @todo this could move to its own class, much like
@@ -691,8 +842,31 @@ module Accessibility::DSL
   end
   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}'`
+  #
+  # @param file [String]
+  # @yield
+  # @yieldparam recorder [ScreenRecorder]
+  # @return [String]
+  def record file = nil, &block
+    require 'screen_recorder'
+    if file
+      ScreenRecorder.record file, &block
+    else
+      ScreenRecorder.record &block
+    end
+  end
 
-  # @endgroup
+  # @!endgroup
 
 
   ##
@@ -704,10 +878,10 @@ module Accessibility::DSL
   #   app_with_bundle_identifier 'com.apple.finder'
   #   launch                     'com.apple.mail'
   #
-  # @param [String]
+  # @param id [String]
   # @return [AX::Application,nil]
   def app_with_bundle_identifier id
-    Accessibility.application_with_bundle_identifier id
+    AX::Application.new id
   end
   alias_method :app_with_bundle_id, :app_with_bundle_identifier
   alias_method :launch,             :app_with_bundle_identifier
@@ -721,7 +895,7 @@ module Accessibility::DSL
   #
   #   app_with_name 'Finder'
   #
-  # @param [String]
+  # @param name [String]
   # @return [AX::Application,nil]
   def app_with_name name
     AX::Application.new name
@@ -735,14 +909,14 @@ module Accessibility::DSL
   #
   #   app_with_pid 35843
   #
-  # @param [Fixnum]
+  # @param pid [Fixnum]
   # @return [AX::Application]
   def app_with_pid pid
     AX::Application.new pid
   end
 
   ##
-  # Convenience for `AX::SystemWide.new`.
+  # Synonym for `AX::SystemWide.new`.
   #
   # @return [AX::SystemWide]
   def system_wide
@@ -775,8 +949,8 @@ module Accessibility::DSL
   #
   #   element_at window # find out what is in the middle of the window
   #
-  # @param [#to_point]
-  # @param [Hash] opts
+  # @param point [#to_point]
+  # @param opts [Hash]
   # @option opts [AX::Application] :for
   # @return [AX::Element]
   def element_at_point point, opts = {}