AXElements 0.6.0beta2 → 0.7.5

data/lib/ax_elements/accessibility/enumerators.rb

@@ -1,104 +0,0 @@
-##
-# @abstract
-#
-# Common code for all enumerators.
-class Accessibility::AbstractEnumerator
-  include Enumerable
-
-  ##
-  # Caches the root.
-  #
-  # @param [AX::Element] root
-  def initialize root
-    @root = root
-  end
-
-end
-
-##
-# Enumerator for visiting each element in a UI hierarchy in breadth
-# first order.
-class Accessibility::BFEnumerator < Accessibility::AbstractEnumerator
-
-  ##
-  # @todo Lazy-wrap element refs, might make things a bit faster
-  #       for fat trees; what is impact on thin trees?
-  # @todo See if we can implement method in a single loop
-  #
-  # Semi-lazily iterate through the tree.
-  #
-  # @yieldparam [AX::Element] element a descendant of the root element
-  def each
-    queue = [@root]
-    until queue.empty?
-      queue.shift.attribute(:children).each do |x|
-        queue << x if x.attributes.include? KAXChildrenAttribute
-        yield x
-      end
-    end
-  end
-
-  ##
-  # 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.
-  def find
-    each { |x| return x if yield x }
-  end
-
-end
-
-##
-# Enumerator for visitng each element in a UI hierarchy in
-# depth first order.
-class Accessibility::DFEnumerator < Accessibility::AbstractEnumerator
-
-  # @yieldparam [AX::Element] element a descendant of the root
-  def each
-    stack = @root.attribute(:children)
-    until stack.empty?
-      current = stack.shift
-      yield current
-      if current.attributes.include? KAXChildrenAttribute
-        # need to reverse it since child ordering seems to matter in practice
-        stack.unshift *current.attribute(:children)
-      end
-    end
-  end
-
-  ##
-  # @todo A bit of a hack that I would like to fix one day...
-  #
-  # Walk the UI element tree and yield both the element and the depth
-  # in three relative to the root.
-  #
-  # @yieldparam [AX::Element]
-  # @yieldparam [Number]
-  def each_with_height &block
-    @root.attribute(:children).each do |element|
-      recursive_each_with_height element, 1, block
-    end
-  end
-
-
-  private
-
-  ##
-  # Recursive implementation of a depth first iterator.
-  #
-  # @param [AX::Element]
-  # @param [Number]
-  # @param [#call]
-  def recursive_each_with_height element, depth, block
-    block.call element, depth
-    if element.attributes.include? KAXChildrenAttribute
-      element.attribute(:children).each do |x|
-        recursive_each_with_height x, depth + 1, block
-      end
-    end
-  end
-
-end

data/lib/ax_elements/accessibility/graph.rb

@@ -1,118 +0,0 @@
-##
-# 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/accessibility/language.rb

@@ -1,347 +0,0 @@
-# -*- coding: utf-8 -*-
-
-require 'mouse'
-
-##
-# @todo Allow the animation duration to be overridden for Mouse stuff?
-#
-# 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.
-module Accessibility::Language
-
-  # @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
-  def method_missing method, *args
-    arg = args.first
-    unless arg.kind_of? AX::Element
-      # should be able to just call super, but there is a bug in MacRuby (#1320)
-      # so we just recreate what should be happening
-      message = "undefined method `#{method}' for #{self}:#{self.class}"
-      raise NoMethodError, message
-    end
-    arg.perform_action method
-  end
-
-  ##
-  # Try to perform the `press` action on the given element.
-  #
-  # @param [AX::Element]
-  # @return [Boolean]
-  def press element
-    element.perform_action :press
-  end
-
-  ##
-  # Try to perform the `show_menu` action on the given element.
-  #
-  # @param [AX::Element]
-  # @return [Boolean]
-  def show_menu element
-    element.perform_action :show_menu
-  end
-
-  ##
-  # Try to perform the `pick` action on the given element.
-  #
-  # @param [AX::Element]
-  # @return [Boolean]
-  def pick element
-    element.perform_action :pick
-  end
-
-  ##
-  # Try to perform the `decrement` action on the given element.
-  #
-  # @param [AX::Element]
-  # @return [Boolean]
-  def decrement element
-    element.perform_action :decrement
-  end
-
-  ##
-  # Try to perform the `confirm` action on the given element.
-  #
-  # @param [AX::Element]
-  # @return [Boolean]
-  def confirm element
-    element.perform_action :confirm
-  end
-
-  ##
-  # Try to perform the `increment` action on the given element.
-  #
-  # @param [AX::Element]
-  # @return [Boolean]
-  def increment element
-    element.perform_action :increment
-  end
-
-  ##
-  # Try to perform the `delete` action on the given element.
-  #
-  # @param [AX::Element]
-  # @return [Boolean]
-  def delete element
-    element.perform_action :delete
-  end
-
-  ##
-  # Try to perform the `cancel` action on the given element.
-  #
-  # @param [AX::Element]
-  # @return [Boolean]
-  def cancel element
-    element.perform_action :cancel
-  end
-
-  ##
-  # Tell an app to hide itself.
-  #
-  # @param [AX::Application]
-  # @return [Boolean]
-  def hide app
-    app.perform_action :hide
-  end
-
-  ##
-  # Tell an app to unhide itself, which does not guarantee it will be
-  # focused.
-  #
-  # @param [AX::Application]
-  # @return [Boolean]
-  def unhide app
-    app.perform_action :unhide
-  end
-
-  ##
-  # Tell an app to quit.
-  #
-  # @param [AX::Application]
-  # @return [Boolean]
-  def terminate app
-    app.perform_action :terminate
-  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 `press` 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_action(:raise) : super
-  end
-
-  ##
-  # Focus an element on the screen, but do not set focus again if
-  # already focused.
-  #
-  # @param [AX::Element]
-  def set_focus element
-    element.set_attribute(:focused, true) unless element.attribute(:focused?)
-  end
-
-  ##
-  # @note We try to set focus to the element first; this is to avoid false
-  #       positives where developers assumed an element would have to have
-  #       focus before a user could change the value.
-  #
-  # You would think that the `#set` method should belong to {AX::Element},
-  # but I think taking it out of the class and putting it in front helps
-  # make the difference between performing actions and inspecting UI more
-  # concrete.
-  #
-  # @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
-  #
-  # @overload set element, new_value
-  #   Set the `value` attribute to a new value
-  #   @param [AX::Element] element
-  #   @param [Object] change
-  #
-  # @return [nil] do not rely on a return value
-  def set element, change
-    set_focus element if element.attribute_writable? :focused
-    key, value = change.is_a?(Hash) ? change.first : [:value, change]
-    element.set_attribute key, value
-  end
-
-  ##
-  # 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}.
-  #
-  # @overload type string
-  #   Send input to the currently focused application
-  #   @param [#to_s]
-  #
-  # @overload type string, app
-  #   Send input to a specific application
-  #   @param [#to_s]
-  #   @param [AX::Application]
-  def type string, app = AX::SYSTEM
-    app.type_string string.to_s
-  end
-
-  # @group Notifications
-
-  ##
-  # @todo Change this to `register_for_notification:from:` when the
-  #       syntax is supported by YARD (v0.8) or someone complains,
-  #       which ever comes first.
-  #
-  # @param [AX::Element]
-  # @param [String]
-  def register_for_notification element, notif, &block
-    element.on_notification notif, &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
-  def wait_for_notification timeout = 10.0
-    AX.wait_for_notif(timeout).tap { |_| unregister_notifications }
-  end
-
-  ##
-  # Undo _all_ notification registries.
-  def unregister_notifications
-    AX.unregister_notifs
-  end
-
-  # @group Mouse Input
-
-  ##
-  # @overload move_mouse_to(element)
-  #   Move the mouse to a UI element
-  #   @param [AX::Element]
-  #
-  # @overload move_mouse_to(point)
-  #   Move the mouse to an arbitrary point
-  #   @param [CGPoint]
-  #
-  # @overload move_mouse_to([x,y])
-  #   Move the mouse to an arbitrary point given as an two element array
-  #   @param [Array(Float,Float)]
-  def move_mouse_to arg
-    Mouse.move_to arg.to_point
-  end
-
-  ##
-  # 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.
-  #
-  # This method will drag the mouse from its current point on the screen
-  # to the point given by calling `#to_point` on the argument.
-  #
-  # Generally, you will pass a {CGPoint} or some kind of {AX::Element},
-  # but you could pass anything that responds to #to_point.
-  #
-  # @param [#to_point]
-  def drag_mouse_to arg
-    Mouse.drag_to point.to_point
-  end
-
-  ##
-  # @todo Need to expose the units option? Would allow scrolling by pixel.
-  #
-  # Scrolls an arbitrary number of lines at the mouses current point on
-  # the screen. Use a positive number to scroll down, and a negative number
-  # to scroll up.
-  #
-  # 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]
-  def scroll lines, obj = nil
-    move_mouse_to obj if obj
-    Mouse.scroll lines
-  end
-
-  ##
-  # Perform a regular click.
-  #
-  # If an argument is provided then the mouse will move to that point
-  # first; the argument must respond to `#to_point`.
-  #
-  # @param [#to_point]
-  def click obj = nil
-    move_mouse_to obj if obj
-    Mouse.click
-  end
-
-  ##
-  # 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`.
-  #
-  # @param [#to_point]
-  def right_click obj = nil
-    move_mouse_to obj if obj
-    Mouse.right_click
-  end
-  alias_method :secondary_click, :right_click
-
-  ##
-  # Perform a double 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]
-  def double_click obj = nil
-    move_mouse_to obj if obj
-    Mouse.double_click
-  end
-
-  # @group Macros
-
-  ##
-  # Show the "About" window for an app.
-  #
-  # @param [AX::Application]
-  def show_about_window_for app
-    set_focus app
-    press app.menu_bar_item(title:(app.title))
-    press app.menu_bar.menu_item(title: "About #{app.title}")
-  end
-
-  ##
-  # Try to open the preferences for an app using the menu bar.
-  #
-  # @param [AX::Application]
-  def show_preferences_window_for app
-    set_focus app
-    press app.menu_bar_item(title:(app.title))
-    press app.menu_bar.menu_item(title:'Preferences…')
-  end
-
-end

data/lib/ax_elements/accessibility/qualifier.rb

@@ -1,73 +0,0 @@
-##
-# Used in searches to answer whether or not a given element meets the
-# expected criteria.
-class Accessibility::Qualifier
-
-  ##
-  # Initialize a qualifier with the kind of object that you want to
-  # qualify and a dictionary of filter criteria.
-  #
-  # @param [String,Symbol]
-  # @param [Hash]
-  def initialize klass, criteria
-    @sym      = klass
-    @criteria = criteria
-  end
-
-  ##
-  # Whether or not a candidate object matches the criteria given
-  # at initialization.
-  #
-  # @param [AX::Element] element
-  def qualifies? element
-    return false unless the_right_type? element
-    return false unless meets_criteria? element
-    return true
-  end
-
-
-  private
-
-  ##
-  # Checks if a candidate object is of the correct class, respecting
-  # that that the class being searched for may not be defined yet.
-  #
-  # @param [AX::Element]
-  def the_right_type? element
-    unless @klass
-      if AX.const_defined? @sym
-        @klass = AX.const_get @sym
-      else
-        return false
-      end
-    end
-    return element.kind_of? @klass
-  end
-
-  ##
-  # @todo How could we handle filters that use parameterized
-  #       attributes?
-  # @todo Optimize searching by compiling filters into an
-  #       optimized filter qualifier. `eval` is not an option.
-  #
-  # Determines if the element meets all the criteria of the filters,
-  # spawning sub-searches if necessary.
-  #
-  # @param [AX::Element] element
-  def meets_criteria? element
-    @criteria.all? do |filter, value|
-      if value.kind_of? Hash
-        if element.attributes.include? KAXChildrenAttribute
-          !element.search(filter, value).blank?
-        else
-          false
-        end
-      elsif element.respond_to? filter
-        element.send(filter) == value
-      else # this legitimately occurs
-        false
-      end
-    end
-  end
-
-end