AXElements 0.6.0beta1

data/ext/key_coder/key_coder.m

@@ -0,0 +1,77 @@
+/*
+ *  key_coder.m
+ *  KeyCoder
+ *
+ *  Created by Mark Rada on 11-07-27.
+ *  Copyright 2011 Marketcircle Incorporated. All rights reserved.
+ */
+
+#import <Foundation/Foundation.h>
+#import <Carbon/Carbon.h>
+#import <CoreServices/CoreServices.h>
+#include "ruby/ruby.h"
+
+/*
+ * @note Static keycode reference at
+ *       /System/Library/Frameworks/Carbon.framework/Versions/A/Frameworks/HIToolbox.framework/Versions/A/Headers/Events.h
+ *
+ * Map of characters to key codes.
+ *
+ * @return [Hash{String=>Fixnum}]
+ */
+static NSMutableDictionary* mAX_keycode_map;
+
+static VALUE mAX;
+
+/*
+ * Helper method to create the keycode mapping at runtime.
+ */
+static void mAX_initialize_keycode_map() {
+
+  TISInputSourceRef currentKeyboard      = TISCopyCurrentKeyboardInputSource();
+  CFDataRef keyboardLayoutData           = (CFDataRef)TISGetInputSourceProperty(currentKeyboard,
+                                                                                kTISPropertyUnicodeKeyLayoutData);
+  const UCKeyboardLayout* keyboardLayout = (const UCKeyboardLayout*)CFDataGetBytePtr(keyboardLayoutData);
+  UInt32                    deadKeyState = 0;
+  UniCharCount        actualStringLength = 0;
+  UniChar                        string[255];
+
+  mAX_keycode_map = [[NSMutableDictionary alloc] initWithCapacity:255];
+
+  for (int keyCode = 0; keyCode < 255; keyCode++) {
+    UCKeyTranslate (
+                    keyboardLayout,
+                    keyCode,
+                    kUCKeyActionDown,
+                    0,
+                    0, // kb type
+                    0, // OptionBits keyTranslateOptions,
+                    &deadKeyState,
+                    255,
+                    &actualStringLength,
+                    string
+                    );
+
+    [mAX_keycode_map setObject:[NSNumber numberWithInt:keyCode]
+                        forKey:[NSString stringWithFormat:@"%C", string[0]]];
+  }
+
+}
+
+void Init_key_coder() {
+
+  // TODO: Make mapping keys lazy, expose a C function to map a single
+  //       character to a keycode, and define a hash in Ruby land that
+  //       will use the hash callback feature to get the mapping on demand.
+  //       POSSIBLE PROBLEM: How to handle alternative characters, like
+  //       symbols which require holding shift first? How would we know
+  //       about them?
+
+  // Initialize the mapping and expose it as a constant in the AX module
+  mAX_initialize_keycode_map();
+  mAX = rb_define_module("AX");
+  rb_define_const(mAX, "KEYCODE_MAP", (VALUE)mAX_keycode_map);
+  // No need to expose the method right now...
+  //rb_define_module_function(mAX, "initialize_keycode_map", mAX_initialize_keycode_map, 0);
+
+}

data/lib/ax_elements/accessibility/enumerators.rb

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

@@ -0,0 +1,347 @@
+# -*- 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

@@ -0,0 +1,73 @@
+##
+# 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