AXElements 0.7.8 → 0.8.0

data/lib/accessibility/dsl.rb

@@ -5,18 +5,16 @@ require 'ax/element'
 require 'ax/application'
 require 'ax/systemwide'
 require 'accessibility'
-require 'accessibility/debug'
+require 'accessibility/enumerators'
 
 ##
-# @todo Allow the animation duration to be overridden for Mouse stuff?
-#
 # DSL methods for AXElements.
 #
 # The idea here is to pull actions out from an object and put them
 # in front of object to give AXElements more of a DSL feel to make
 # communicating test steps more clear. See the
-# {file:docs/Acting.markdown Acting tutorial} for examples on how to use
-# methods from this module.
+# [Acting tutorial](http://github.com/Marketcircle/AXElements/wiki/Acting)
+# for a more in depth tutorial on using this module.
 module Accessibility::DSL
 
 
@@ -113,6 +111,23 @@ module Accessibility::DSL
     element.perform :cancel
   end
 
+  ##
+  # @note This method overrides `Kernel#raise` so we have to check the
+  #       class of the first argument to decide which code path to take.
+  #
+  # Try to perform the `raise` action on the given element.
+  #
+  # @overload raise element
+  #   @param [AX::Element] 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)
+  end
+
   ##
   # Tell an app to hide itself.
   #
@@ -123,8 +138,7 @@ module Accessibility::DSL
   end
 
   ##
-  # Tell an app to unhide itself. This does not guarantee it will be
-  # focused.
+  # Tell an app to unhide itself.
   #
   # @param [AX::Application]
   # @return [Boolean]
@@ -143,16 +157,16 @@ module Accessibility::DSL
   end
 
   ##
-  # Find the application with the given bundle identifier.
-  # If the application is not already running, it will be
-  # launched.
+  # Find the application with the given bundle identifier. If the
+  # application is not already running, it will be launched.
   #
   # @example
   #
-  #   app_with_identifier 'com.apple.finder'
+  #   app_with_bundle_identifier 'com.apple.finder'
+  #   launch                     'com.apple.mail'
   #
   # @param [String]
-  # @return [AX::Application]
+  # @return [AX::Application,nil]
   def app_with_bundle_identifier id
     Accessibility.application_with_bundle_identifier id
   end
@@ -160,7 +174,9 @@ module Accessibility::DSL
   alias_method :launch,             :app_with_bundle_identifier
 
   ##
-  # Find the application with the given name.
+  # Find the application with the given name. If the application
+  # is not already running, it will NOT be launched and this
+  # method will return `nil`.
   #
   # @example
   #
@@ -173,7 +189,8 @@ module Accessibility::DSL
   end
 
   ##
-  # Find the application with the given process identifier.
+  # Find the application with the given process identifier. An
+  # invalid PID will cause an exception to be raised.
   #
   # @example
   #
@@ -186,27 +203,9 @@ module Accessibility::DSL
   end
 
   ##
-  # @note This method overrides `Kernel#raise` so we have to check the
-  #       class of the first argument to decide which code path to take.
-  #
-  # Try to perform the `raise` action on the given element.
-  #
-  # @overload raise element
-  #   @param [AX::Element] element
-  #   @return [Boolean]
-  #
-  # @overload raise exception[, message[, backtrace]]
-  #   The normal way to raise an exception.
-  def raise *args
-    arg = args.first
-    # @todo Need to check if arg has the raise action
-    arg.kind_of?(AX::Element) ? arg.perform(:raise) : super
-  end
-
-  ##
-  # Focus an element on the screen if it can be focused. It is safe to
-  # pass any element into this method as nothing will happen if it is
-  # not capable of having focus set on it.
+  # Focus an element on the screen, but only if it can be directly
+  # 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]
   def set_focus_to element
@@ -218,8 +217,8 @@ module Accessibility::DSL
   # Set the value of an attribute on an element.
   #
   # This method will try to set focus to the element first; this is
-  # to avoid cases where developers assumed an element would have
-  # to have focus before a user could change the value.
+  # to compensate for cases where app developers assumed an element
+  # would have to have focus before a user could change the value.
   #
   # @overload set element, attribute_name: new_value
   #   Set a specified attribute to a new value
@@ -228,7 +227,7 @@ module Accessibility::DSL
   #
   # @example
   #
-  #   set text_field, selected_text_range: CFRangeMake(1,10)
+  #   set text_field, selected_text_range: 1..10
   #
   # @overload set element, new_value
   #   Set the `value` attribute to a new value
@@ -240,7 +239,6 @@ module Accessibility::DSL
   #   set text_field,   'Mark Rada'
   #   set radio_button, 1
   #
-  # @return [nil] do not rely on a return value
   def set element, change
     set_focus_to element
 
@@ -255,12 +253,17 @@ module Accessibility::DSL
   # Simulate keyboard input by typing out the given string. To learn
   # more about how to encode modifier keys (e.g. Command), see the
   # dedicated documentation page on
-  # {file:docs/KeyboardEvents.markdown Keyboard Events}.
+  # [Keyboard Events](http://github.com/Marketcircle/AXElements/wiki/Keyboarding)
+  # wiki page.
   #
   # @overload type string
   #   Send input to the currently focused application
   #   @param [#to_s]
   #
+  # @example
+  #
+  #   type "Hello, world!"
+  #
   # @overload type string, app
   #   Send input to a specific application
   #   @param [#to_s]
@@ -270,6 +273,7 @@ module Accessibility::DSL
     sleep 0.1
     app.type string.to_s
   end
+  alias_method :type_string, :type
 
   ##
   # Navigate the menu bar menus for the given application and select
@@ -289,75 +293,16 @@ module Accessibility::DSL
   end
 
 
-  # @group Notifications
-
-  ##
-  # Register for a notification from a specific element.
-  #
-  # @param [#to_s]
-  # @param [Array(#to_s,AX::Element)]
-  def register_for notif, from: element, &block
-    @registered_elements ||= []
-    @registered_elements << element
-    element.on_notification notif, &block
-  end
-
-  ##
-  # @deprecated This API exists for backwards compatability only
-  #
-  # Register for a notification from a specific element.
-  #
-  # @param [AX::Element]
-  # @param [String]
-  def register_for_notification element, notif, &block
-    register_for notif, from: element, &block
-  end
-
-  ##
-  # Pause script execution until notification that has been registered
-  # for is received or the full timeout period has passed.
-  #
-  # If the script is unpaused because of a timeout, then it is assumed
-  # that the notification was never received and all notification
-  # registrations will be unregistered to avoid future complications.
-  #
-  # @param [Float] timeout number of seconds to wait for a notification
-  # @return [Boolean]
-  def wait_for_notification timeout = 10.0
-    # We use RunInMode because it has timeout functionality
-    case CFRunLoopRunInMode(KCFRunLoopDefaultMode, timeout, false)
-    when KCFRunLoopRunStopped       then true
-    when KCFRunLoopRunTimedOut      then false.tap { |_| unregister_notifications }
-    when KCFRunLoopFinished         then
-      raise RuntimeError, 'The run loop was not configured properly'
-    when KCFRunLoopRunHandledSource then
-      raise RuntimeError, 'Did you start your own run loop?'
-    else
-      raise 'You just found a bug, might be yours, or OS X, or MacRuby...'
-    end
-  end
-
-  ##
-  # Undo _all_ notification registries.
-  def unregister_notifications
-    return unless @registered_elements
-    @registered_elements.each do |element|
-      element.unregister_notifications
-    end
-    @registered_elements = []
-  end
-
-
   # @group Polling
 
   ##
-  # Simply wait around for something to show up. This method is similar to
-  # performing an explicit search on an element except that the search filters
-  # take two extra options which can control how long to wait and from where
-  # to start searches from. You __MUST__ supply either the parent or ancestor
-  # options to specify where to search from. Searching from the parent implies
-  # that what you are waiting for is a child of the parent and not a more
-  # distant descendant.
+  # Simply wait around for something to show up. This method is similar
+  # to performing an explicit search on an element except that the search
+  # filters take two extra options which can control the timeout period
+  # and the search subtree. You __MUST__ supply either the parent or
+  # ancestor option to specify where to search from. Searching from the
+  # parent implies that what you are waiting for is a child of the parent
+  # and not a more distant descendant.
   #
   # This is an alternative to using the notifications system. It is far
   # easier to use than notifications in most cases, but it will perform
@@ -375,18 +320,18 @@ module Accessibility::DSL
   #   wait_for :a_million_dollars, ancestor: fruit_basket, timeout: 1000000
   #
   # @param [#to_s]
-  # @param [Hash] opts
-  # @options opts [Number] :timeout (15)
-  # @options opts [AX::Element] :parent
-  # @options opts [AX::Element] :ancestor
+  # @param [Hash] filters
+  # @option filters [Number] :timeout (5) timeout in seconds
+  # @option filters [AX::Element] :parent
+  # @option filters [AX::Element] :ancestor
   # @return [AX::Element,nil]
-  def wait_for element, opts = {}, &block
-    if opts.has_key? :ancestor
-      wait_for_descendant element, opts.delete(:ancestor), opts, &block
-    elsif opts.has_key? :parent
-      wait_for_child element, opts.delete(:parent), opts, &block
+  def wait_for element, filters = {}, &block
+    if filters.has_key? :ancestor
+      wait_for_descendant element, filters.delete(:ancestor), filters, &block
+    elsif filters.has_key? :parent
+      wait_for_child element, filters.delete(:parent), filters, &block
     else
-      raise ArgumentError, 'parent/ancestor opt required'
+      raise ArgumentError, 'parent/ancestor filter required'
     end
   end
 
@@ -395,17 +340,19 @@ module Accessibility::DSL
   # The options you pass to this method can be any search filter that
   # you can normally use.
   #
+  # See {#wait_for} for more details.
+  #
   # @param [#to_s]
   # @param [AX::Element]
   # @param [Hash]
   # @return [AX::Element,nil]
-  def wait_for_descendant descendant, ancestor, opts, &block
-    timeout = opts.delete(:timeout) || 15
+  def wait_for_descendant descendant, ancestor, filters, &block
+    timeout = filters.delete(:timeout) || 5
     start   = Time.now
     until Time.now - start > timeout
-      result = ancestor.search(descendant, opts, &block)
+      result = ancestor.search(descendant, filters, &block)
       return result unless result.blank?
-      sleep 0.2
+      sleep 0.1
     end
     nil
   end
@@ -414,49 +361,105 @@ module Accessibility::DSL
   ##
   # @note This is really just an optimized case of
   #       {#wait_for_descendant} when you know what you are waiting
-  #       for is a child of a particular element.
+  #       for is a child of a particular element. Use
+  #       {#wait_for_descendant} if you are unsure of the relationship.
   #
   # Wait around for particular element and then return that element.
-  # The parent option must be the parent of the element you are
+  # The parent argument must be the parent of the element you are
   # waiting for, this method will not look further down the hierarchy.
   # The options you pass to this method can be any search filter that
   # you can normally use.
   #
+  # See {#wait_for} for more details.
+  #
   # @param [#to_s]
   # @param [AX::Element]
   # @param [Hash]
   # @return [AX::Element,nil]
-  def wait_for_child child, parent, opts, &block
-    timeout = opts.delete(:timeout) || 15
+  def wait_for_child child, parent, filters, &block
+    timeout = filters.delete(:timeout) || 5
     start   = Time.now
-    q       = Accessibility::Qualifier.new(child, opts, &block)
+    q       = Accessibility::Qualifier.new(child, filters, &block)
     until Time.now - start > timeout
       result = parent.children.find { |x| q.qualifies? x }
       return result unless result.blank?
-      sleep 0.2
+      sleep 0.1
     end
     nil
   end
 
+  ##
+  # Simply wait for an element to disappear. Optionally wait for the
+  # element to appear first.
+  #
+  # Like {#wait_for}, you can pass any search filters that you normally
+  # would, including blocks. However, this method also supports the
+  # ability to pass an {AX::Element} and simply wait for it to become
+  # invalid.
+  #
+  # An example usage would be typing into a search field and then
+  # waiting for the busy indicator to disappear and indicate that
+  # all search results have been returned.
+  #
+  # @overload wait_for_invalidation_of element
+  # @param [AX::Element]
+  # @param [Hash] filters
+  # @option filters [Number] :timeout (5) in seconds
+  # @return [Boolean]
+  #
+  # @example
+  #
+  #   wait_for_invalidation_of table.row(static_text: { value: 'Cake' })
+  #
+  # @overload wait_for_invalidation_of kind, filters = {}, &block
+  # @param [#to_s]
+  # @param [Hash] filters
+  # @option filters [Number] :timeout (5) in seconds
+  # @return [Boolean]
+  #
+  # @example
+  #
+  #   wait_for_invalidation_of :row, parent: table, static_text: { value: 'Cake' }
+  #
+  # @return [Boolean]
+  def wait_for_invalidation_of element, filters = {}, &block
+    timeout = filters[:timeout] || 5
+    start   = Time.now
+
+    unless element.kind_of? AX::Element
+      element = wait_for element, filters, &block
+      # this is a tricky situation,
+      return true unless element
+    end
+
+    until Time.now - start > timeout
+      return true if element.invalid?
+      sleep 0.1
+    end
+    false
+  end
+  alias_method :wait_for_invalidation, :wait_for_invalidation_of
+  alias_method :wait_for_invalid,      :wait_for_invalidation_of
+
 
-  # @group Mouse Interaction
+  # @group Mouse Manipulation
 
   ##
-  # Move the mouse cursor to the given point on the screen.
+  # Move the mouse cursor to the given point or object on the screen.
   #
   # @example
   #
   #  move_mouse_to button
   #  move_mouse_to [344, 516]
-  #  move_mouse_to CGPointMake(100, 100)
+  #  move_mouse_to CGPoint.new(100, 100)
   #
   # @param [#to_point]
   # @param [Hash] opts
-  # @option opts [Number] :duration
-  # @option opts [Number] :wait
+  # @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.on? && arg.respond_to?(:bounds)
+    if Accessibility.debug? && arg.respond_to?(:bounds)
       highlight arg, timeout: duration, color: NSColor.orangeColor
     end
     Mouse.move_to arg.to_point, duration
@@ -469,25 +472,24 @@ module Accessibility::DSL
   #
   # There are many reasons why you would want to cause a drag event
   # with the mouse. Perhaps you want to drag an object to another
-  # place, or maybe you want to hightlight an area of the screen.
+  # place, or maybe you want to select a group of objects on the screen.
+  #
+  # @example
+  #
+  #   drag_mouse_to [100,100]
+  #   drag_mouse_to drop_zone, from: desktop_icon
   #
   # @param [#to_point]
+  # @param [Hash] opts
+  # @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
   def drag_mouse_to arg, opts = {}
+    move_mouse_to opts[:from] if opts[:from]
     Mouse.drag_to arg.to_point, (opts[:duration] || 0.2)
     sleep(opts[:wait] || 0.2)
   end
 
-  ##
-  # Move the mouse to the first point and then drag to the second point.
-  #
-  # @param [#to_point]
-  # @param [#to_point]
-  def drag arg1, to: arg2
-    move_mouse_to obj
-    drag_mouse_to obj2
-  end
-
-
   ##
   # @todo Need to expose the units option? Would allow scrolling by pixel.
   #
@@ -509,13 +511,27 @@ module Accessibility::DSL
   ##
   # Perform a regular click.
   #
-  # If an argument is provided then the mouse will move to that point
+  # If a parameter 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.
+  #
+  # @example
+  #
+  #   click
+  #   click window.close_button
+  #
   # @param [#to_point]
   def click obj = nil, wait = 0.2
     move_mouse_to obj, wait: 0 if obj
-    Mouse.click
+    if block_given?
+      Mouse.click_down
+      yield
+      Mouse.click_up
+    else
+      Mouse.click
+    end
     sleep wait
   end
 
@@ -547,36 +563,122 @@ module Accessibility::DSL
   end
 
 
-  # @group Debug
+  # @group Debug Helpers
 
-  def highlight element, opts = {}
-    Accessibility::Debug.highlight element, opts
+  ##
+  # Highlight an element on screen. You can optionally specify the
+  # highlight colour or pass a timeout to automatically have the
+  # highlighter disappear.
+  #
+  # The highlighter is actually a window, so if you do not set a
+  # timeout, you will need to call `#stop` or `#close` on the returned
+  # highlighter object in order to get rid of the highlighter.
+  #
+  # You could use this method to highlight an arbitrary number of
+  # elements on screen, with a rainbow of colours. Great for debugging.
+  #
+  # @example
+  #
+  #   highlighter = highlight window.outline
+  #   # wait a few seconds...
+  #   highlighter.stop
+  #
+  #   # highlighter automatically turns off after 5 seconds
+  #   highlight window.outline.row, colour: NSColor.greenColor, timeout: 5
+  #
+  # @param [#bounds]
+  # @param [Hash] opts
+  # @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
 
-  def path_for element
-    Accessibility::Debug.path element
+  ##
+  # 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_for app
+  #
+  # @return [String]
+  def subtree_for element
+    element.inspect_subtree
   end
+  alias_method :subtree, :subtree_for
 
-  def subtree_for element
-    # @todo Create Element#descendants
-    Accessibility::Debug.text_subtree element
+  ##
+  # @note You will need to have GraphViz command line tools installed
+  #       in order for this to work.
+  #
+  # Make and open a `dot` format graph of the tree, meant for graphing
+  # with GraphViz.
+  #
+  # @example
+  #
+  #   graph app.main_window
+  #
+  # @param [AX::Element]
+  # @return [String] path to the saved image
+  def graph element
+    require 'accessibility/graph'
+    graph = Accessibility::Graph.new(element)
+    graph.build!
+
+    require 'tempfile'
+    file = Tempfile.new('graph')
+    File.open(file.path, 'w') do |fd| fd.write graph.to_dot end
+    `dot -Tpng #{file.path} > #{file.path}.png`
+    `open #{file.path}.png`
+
+    file.path
   end
 
   ##
-  # @note This is an unfinished feature
+  # Take a screen shot and save it to disk. If a file name and path are
+  # not given then default values will be used; given paths will be
+  # expanded automatically.A timestamp and file extension will always
+  # automatically be appended to the file name.
   #
-  # Make a `dot` format graph of the tree, meant for graphing with
-  # GraphViz.
+  # @example
   #
-  # @return [String]
-  def graph element, open = true
-    Accessibility::Debug.graph_subtree element
-    # @todo Use the `open` flag to decide if it should be sent to
-    #       graphviz and opened right away
+  #   screenshot
+  #     # => "~/Desktop/AXElements-ScreenShot-20120422184650.png"
+  #
+  #   screenshot app.title
+  #     # => "~/Desktop/Safari-20120422184650.png"
+  #
+  #   screenshot app.title, "/Volumes/SecretStash"
+  #     # => "/Volumes/SecretStash/Safari-20120422184650.png"
+  #
+  # @param [#to_s]
+  # @param [#to_s]
+  # @return [String] path to the screenshot
+  def screenshot name = "AXElements-ScreenShot", dir = '~/Desktop'
+    dir  = File.expand_path dir.to_s
+    file = "#{dir}/#{name}-#{Time.now.strftime '%Y%m%d%H%M%S'}.png"
+
+    cg_image = CGWindowListCreateImage(CGRectInfinite,
+                                       KCGWindowListOptionOnScreenOnly,
+                                       KCGNullWindowID,
+                                       KCGWindowImageDefault)
+    NSBitmapImageRep
+      .alloc
+      .initWithCGImage(cg_image)
+      .representationUsingType(NSPNGFileType, properties: nil)
+      .writeToFile(file, atomically: false)
+
+    file
   end
+  alias_method :capture_screen, :screenshot
+  alias_method :shoot_screen,   :screenshot
 
 
-  # @group Misc.
+  # @group Macros
 
   ##
   # Convenience for `AX::SystemWide.new`.
@@ -586,12 +688,10 @@ module Accessibility::DSL
     AX::SystemWide.new
   end
 
-
-  # @group Macros
-
   ##
-  # Get the current mouse position and return the top most element at
-  # that point.
+  # Return the top most element at the current mouse position.
+  #
+  # See {#element_at_point} for more details.
   #
   # @return [AX::Element]
   def element_under_mouse
@@ -603,20 +703,24 @@ module Accessibility::DSL
   # the given application. The given point can be a CGPoint, an Array,
   # or anything else that responds to `#to_point`.
   #
-  # @param [#to_point]
-  # @return [AX::Element]
-  def element_at_point point, for: app
-    app.element_at point
-  end
-
-  ##
-  # Get the top most object at an arbitrary point on the screen. The
-  # given point can be a CGPoint, an Array, or anything else that
-  # responds to `#to_point`.
+  # Optionally, you can look for the top-most element for a specific
+  # application by passing an {AX::Application} object using the `for:`
+  # key.
+  #
+  # @example
+  #
+  #   element_at [100, 456]
+  #   element_at CGPoint.new(33, 45), for: safari
+  #
+  #   element_at window # find out what is in the middle of the window
   #
   # @param [#to_point]
-  def element_at_point point
-    system_wide.element_at point
+  # @param [Hash] opts
+  # @option opts [AX::Application] :for
+  # @return [AX::Element]
+  def element_at_point point, opts = {}
+    base = opts[:for] || system_wide
+    base.element_at point
   end
 
   ##
@@ -643,14 +747,18 @@ module Accessibility::DSL
   end
 
   ##
-  # Scroll though a table until the given element is visible.
+  # Scroll though a scroll area until the given element is visible.
   #
   # If you need to scroll an unknown ammount of units through a scroll area
   # you can just pass the element that you need visible and this method
   # will scroll to it for you.
   #
+  # @example
+  #
+  #   scroll_to table.rows.last
+  #
   # @param [AX::Element]
-  # @return [Boolean]
+  # @return [void]
   def scroll_to element
     scroll_area = element.ancestor :scroll_area
 
@@ -663,29 +771,40 @@ module Accessibility::DSL
     end
     sleep 0.1
   end
+  alias_method :scroll_to_visible, :scroll_to
 
   ##
-  # Scroll a popup menu to an item in the menu and then move the
-  # mouse pointer to that item.
+  # Scroll a menu to an item in the menu and then move the mouse
+  # pointer to that item.
   #
-  # @param [AX::Element]
-  # @return [Boolean]
+  # @example
+  #
+  #   scroll_menu_to menu.element(title: "Expensive Cake")
+  #
+  # @param [AX:]
+  # @return [void]
   def scroll_menu_to element
     menu = element.ancestor :menu
     move_mouse_to menu
 
-    direction = element.position.y > menu.position.y ? -5 : 5
+    row_height = menu.menu_item.size.height
+    point = menu.position
+    point.x += menu.size.width / 2
+    point.y += if element.position.y > menu.position.y
+                 menu.size.height - (row_height * 0.1)
+               else
+                 row_height * 0.1
+               end
+
     until NSContainsRect(menu.bounds, element.bounds)
-      Mouse.scroll direction
+      move_mouse_to point
     end
 
     start = Time.now
     until Time.now - start > 5
       # This can happen sometimes with the little arrow bars
       # in menus covering up the menu item.
-      if element_under_mouse.kind_of? AX::Menu
-        scroll direction
-      elsif element_under_mouse != element
+      if element_under_mouse != element
         move_mouse_to element
       else
         break