AXElements 0.6.0beta1

data/lib/ax_elements/elements/row.rb

@@ -0,0 +1,30 @@
+##
+# UI Element for the row in a table, outline, etc.
+class AX::Row < AX::Element
+
+  ##
+  # @todo Can this be more efficient? It wraps the columns twice,
+  #       which is expensive if there are many columns. Needs to be
+  #       done in such that we preserve search semantics for the
+  #       filters.
+  #
+  # Retrieve the child in a row that corresponds to a specific column.
+  # You must pass filters here in the same way that you would for a
+  # search.
+  #
+  # @example
+  #
+  #   table.row[5].child_in_column(header: 'Price')
+  #
+  # @param [Hash]
+  # @return [AX::Element]
+  def child_in_column filters
+    table   = self.parent
+    column  = table.column(filters)
+    columns = table.columns
+    index   = columns.index { |x| x == column }
+    return self.children.at(index) if index
+    raise AX::Element::SearchFailure.new(self.parent, 'column', filters)
+  end
+
+end

data/lib/ax_elements/elements/static_text.rb

@@ -0,0 +1,17 @@
+##
+# Represents text on the screen that cannot directly be changed by
+# a user, usually a label or an instructional text block.
+class AX::StaticText < AX::Element
+
+  ##
+  # Test equality with another object. Equality can be with another
+  # {AX::Element} or it can be with a string that matches the value
+  # of the static text.
+  #
+  # @return [Boolean]
+  def == other
+    return super unless other.kind_of? NSString
+    return attribute(:value) == other
+  end
+
+end

data/lib/ax_elements/elements/systemwide.rb

@@ -0,0 +1,46 @@
+require 'singleton'
+
+##
+# Represents the special `SystemWide` accessibility object.
+class AX::SystemWide < AX::Element
+  include Singleton
+
+  ##
+  # Overridden since there is only one way to get the element ref.
+  def initialize
+    ref = AXUIElementCreateSystemWide()
+    super ref, AX.attrs_of_element(ref)
+  end
+
+  ##
+  # @note With the `SystemWide` class, using {#type_string} will send the
+  #       events to which ever app has focus.
+  #
+  # Generate keyboard events by simulating keyboard input.
+  def type_string string
+    AX.keyboard_action @ref, string
+  end
+
+  ##
+  # Overridden to avoid a difficult to understand error message.
+  def search *args
+    raise NoMethodError, 'AX::SystemWide cannot search'
+  end
+
+  ##
+  # Raises an `NoMethodError` instead of (possibly) silently failing to
+  # register for a notification.
+  #
+  # @raise [NoMethodError]
+  def on_notification *args
+    raise NoMethodError, 'AX::SystemWide cannot register for notifications'
+  end
+
+end
+
+
+##
+# Singleton instance of the SystemWide element
+#
+# @return [AX::SystemWide]
+AX::SYSTEM = AX::SystemWide.instance

data/lib/ax_elements/inspector.rb

@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+
+##
+# Convenience methods to use when building an `#inspect` method for
+# {AX::Element} and its descendants.
+#
+# The module only expects three methods in order to operate:
+#
+#  - `#attributes` returns a list of available attributes
+#  - `#attribute` returns the value of a given attribute
+#  - `#size_of` returns the size for an attribute
+#
+module Accessibility::PPInspector
+
+
+  protected
+
+  ##
+  # Added for backwards compatability with Snow Leopard.
+  #
+  # @return [String]
+  KAXIdentifierAttribute = 'AXIdentifier'.freeze
+
+  ##
+  # @todo I feel a bit bad about having such a large method that has
+  #       some inefficiencies.
+  #
+  # Create an identifier for `self` using various attributes that should
+  # make it very easy to identify the element.
+  #
+  # @return [String]
+  def pp_identifier
+    # use or lack of use of #inspect is intentional for visual effect
+
+    if attributes.include? KAXValueAttribute
+      val = attribute :value
+      if val.kind_of? NSString
+        return " #{val.inspect}" unless val.empty?
+      else
+        return " value=#{val.inspect}"
+      end
+    end
+
+    if attributes.include? KAXTitleAttribute
+      val = attribute(:title)
+      return " #{val.inspect}" if val && !val.empty?
+    end
+
+    if attributes.include? KAXTitleUIElementAttribute
+      val = attribute :title_ui_element
+      return BUFFER + val.inspect if val
+    end
+
+    if attributes.include? KAXDescriptionAttribute
+      val = attribute(:description).to_s
+      return BUFFER + val unless val.empty?
+    end
+
+    if attributes.include? KAXIdentifierAttribute
+      return " id=#{attribute(:identifier)}"
+    end
+
+    # @todo should we have other fallbacks?
+    return ::EMPTY_STRING
+  end
+
+  ##
+  # Create a string that succinctly encodes the screen coordinates
+  # of `self`.
+  #
+  # @return [String]
+  def pp_position
+    position = attribute :position
+    " (#{position.x}, #{position.y})"
+  end
+
+  ##
+  # Create a string that nicely presents the number of children
+  # that `self` has.
+  #
+  # @return [String]
+  def pp_children
+    child_count = size_of :children
+    if child_count > 1
+      " #{child_count} children"
+    elsif child_count == 1
+      ' 1 child'
+    else # there are some odd edge cases
+      ::EMPTY_STRING
+    end
+  end
+
+  ##
+  # Create a string that looks like a labeled check box. The label
+  # is the given attribute, and the check box value will be
+  # determined by the value of the attribute.
+  #
+  # @param [Symbol]
+  # @return [String]
+  def pp_checkbox attr
+    " #{attr}[#{attribute(attr) ? '✔' : '✘'}]"
+  end
+
+
+  private
+
+  ##
+  # @private
+  #
+  # A string with a single space, used as a buffer. This is a
+  # performance hack.
+  #
+  # @return [String]
+  BUFFER = ' '.freeze
+
+end

data/lib/ax_elements/macruby_extensions.rb

@@ -0,0 +1,255 @@
+require 'active_support/inflector'
+
+##
+# Extensions to `NSArray`.
+class NSArray
+  ##
+  # Equivalent to `#[1]`
+  def second
+    at(1)
+  end
+
+  ##
+  # Equivalent to `#[2]`
+  def third
+    at(2)
+  end
+
+  ##
+  # Create a `CGPoint` from the first two elements in the array.
+  #
+  # @return [CGPoint]
+  def to_point
+    CGPoint.new(first, second)
+  end
+
+  ##
+  # Create a `CGSize` from the first two elements in the array.
+  #
+  # @return [CGSize]
+  def to_size
+    CGSize.new(first, second)
+  end
+
+  ##
+  # Create a `CGRect` from the first four elements in the array.
+  #
+  # @return [CGRect]
+  def to_rect
+    CGRectMake(*self[0,4])
+  end
+
+  ##
+  # @method blank?
+  #
+  # Borrowed from ActiveSupport. Too bad this docstring isn't being
+  # picked up by YARD.
+  alias_method :blank?, :empty?
+
+  alias_method :ax_array_method_missing, :method_missing
+  ##
+  # @todo We should really rethink what this does in terms of the
+  #       semantics of the language. For instance, when we say something
+  #       like "outline.rows.text_field" did we want the text field for
+  #       each row or did we want a row that has a text field or did we
+  #       want the first text field that is a child of one of the rows?
+  #
+  # If the array contains {AX::Element} objects and the method name
+  # belongs to an attribute then the method will be mapped
+  # across the array. In this case, you can artificially pluralize
+  # the attribute name and the lookup will singularize the method name
+  # for you.
+  #
+  # You also have to be careful in cases where the array contains
+  # various types of {AX::Element} objects that may not all respond to
+  # the same attribute.
+  def method_missing method, *args
+    if first.kind_of? AX::Element
+      return map(&method) if first.respond_to?(method)
+      return map(&singularized_method_name(method))
+    end
+    ax_array_method_missing method, *args
+  end
+
+
+  private
+
+  ##
+  # Takes a method name and singularizes it, including the case where
+  # the method name is a predicate.
+  #
+  # @param [Symbol] method
+  # @return [Symbol]
+  def singularized_method_name method
+    (method.predicate? ? method[0..-2] : method).singularize.to_sym
+  end
+end
+
+
+##
+# @private
+#
+# An empty string, performance hack.
+#
+# @return [String]
+EMPTY_STRING = ''.freeze
+
+##
+# Extensions to `NSString`.
+class NSString
+  ##
+  # Used to test a symbol/string representing a method name.
+  # Returns `true` if the string ends with a '?".
+  def predicate?
+    self[-1] == '?'
+  end
+
+  ##
+  # Force the #singularize method to be defined on NSString objects,
+  # and therefore on Symbol objects...at least until that bug gets
+  # fixed.
+  #
+  # @return [String]
+  def singularize
+    ActiveSupport::Inflector.singularize(self)
+  end
+
+  ##
+  # Returns the upper camel case version of the string. The string
+  # is assumed to be in `snake_case`, but still works on a string that
+  # is already in camel case.
+  #
+  # I have this method update the string in-place as it is a fairly hot
+  # method and should perform well; by running in-place we save an
+  # allocation (which is slow on MacRuby right now).
+  #
+  # Returns `nil` the string was empty.
+  #
+  # @return [String,nil] returns `self`
+  def camelize
+    gsub /(?:^|_)(.)/ do $1.upcase! end
+  end
+end
+
+
+##
+# Extensions to `CGPoint`.
+class CGPoint
+  ##
+  # Get the center point in a rectangle.
+  #
+  # @param [CGRect] rect
+  # @return [CGPoint]
+  def self.center_of_rect rect
+    rect.origin.center rect.size
+  end
+
+  ##
+  # Find the center of a rectangle, treating `self` as the origin and
+  # the given `size` as the size of the rectangle.
+  #
+  # @param [CGSize] size
+  # @return [CGPoint]
+  def center size
+    x = self.x + (size.width / 2.0)
+    y = self.y + (size.height / 2.0)
+    CGPoint.new(x, y)
+  end
+
+  ##
+  # @note This method does not show up in the documentation with
+  #       YARD 0.7.x
+  #
+  # @return [CGPoint]
+  alias_method :to_point, :self
+
+  @ax_value = KAXValueCGPointType
+end
+
+
+##
+# Extensions to `Boxed` objects.
+class Boxed
+  class << self
+    ##
+    # The `AXValue` constant for the struct type. Not all structs
+    # have a value.
+    #
+    # @return [AXValueType]
+    attr_reader :ax_value
+  end
+
+  ##
+  # Create an `AXValue` from the `Boxed` instance. This will only
+  # work if for a few boxed types, check the AXAPI documentation.
+  #
+  # @return [AXValueRef]
+  def to_axvalue
+    klass = self.class
+    ptr = Pointer.new klass.type
+    ptr.assign self
+    AXValueCreate(klass.ax_value, ptr)
+  end
+end
+
+
+##
+# Extensions to `CGSize`.
+class CGSize
+  @ax_value = KAXValueCGSizeType
+end
+
+
+##
+# Extensions to `CGRect`.
+class CGRect
+  @ax_value = KAXValueCGRectType
+end
+
+
+##
+# Extensions to `CFRange`.
+class CFRange
+  @ax_value = KAXValueCFRangeType
+end
+
+
+##
+# Extensions to `NilClass`.
+class NilClass
+  ##
+  # Borrowed from Active Support.
+  def blank?
+    true
+  end
+end
+
+
+# ##
+# # Correct a problem with ArgumentError not providing a proper backtrace.
+# class ArgumentError
+#   alias_method :original_message, :message
+#   def message
+#     "#{original_message}\n\t#{backtrace.join("\n\t")}"
+#   end
+# end
+
+
+# ##
+# # Correct a problem with NameError not providing a proper backtrace.
+# class NameError
+#   alias_method :original_message, :message
+#   def message
+#     "#{original_message}\n\t#{backtrace.join("\n\t")}"
+#   end
+# end
+
+
+# ##
+# # Correct a problem with NoMethodError not providing a proper backtrace.
+# class NoMethodError
+#   alias_method :original_message, :message
+#   def message
+#     "#{original_message}\n\t#{backtrace.join("\n\t")}"
+#   end
+# end

data/lib/ax_elements/notification.rb

@@ -0,0 +1,37 @@
+class Accessibility::Notification
+
+  attr_reader :observer
+  attr_reader :element
+  attr_reader :string
+
+  def callback observer, element, notif, refcon
+  end
+
+  def initialize element, string
+    @element = element
+    @string  = string
+  end
+
+  def register
+    code = AXObserverAddNotification(observer, element, string, nil)
+    log_error element, code unless code.zero?
+  end
+
+  def unregister
+    case code = AXObserverRemoveNotification(observer, element, string)
+    when KAXErrorNotificationNotRegistered
+      Accessibility.log.warn  "Notif no longer registered: (#{ref}:#{notif})"
+    when KAXErrorIllegalArgument
+      raise ArgumentError,    "Notif not unregistered (#{ref}:#{notif})"
+    else
+      log_error element, code unless code.zero?
+    end
+  end
+
+  def == other
+    observer  == other.observer &&
+      element == other.element &&
+      string  == other.string
+  end
+
+end

data/lib/ax_elements/version.rb

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+
+module Accessibility
+  # @return [String]
+  VERSION   = '0.6.0beta1'
+
+  # @return [String]
+  CODE_NAME = 'Luxray'
+end

data/lib/ax_elements.rb

@@ -0,0 +1,30 @@
+framework 'Cocoa'
+
+# check that the Accessibility APIs are enabled and are available to MacRuby
+begin
+  unless AXAPIEnabled()
+    raise RuntimeError, <<-EOS
+Universal Access is disabled on this machine. Please enable it in the System Preferences.
+    EOS
+  end
+rescue NoMethodError
+  raise NotImplementedError, <<-EOS
+You need to install the latest BridgeSupport preview for AXElements to work.
+  EOS
+end
+
+require 'ax_elements/macruby_extensions'
+require 'ax_elements/version'
+require 'ax_elements/core'
+require 'ax_elements/element'
+
+require 'ax_elements/accessibility/language'
+
+# Mix the language methods in to the TopLevel
+include Accessibility::Language
+
+##
+# The Mac OS X dock application.
+#
+# @return [AX::Application]
+AX::DOCK = Accessibility.application_with_bundle_identifier 'com.apple.dock'

data/lib/minitest/ax_elements.rb

@@ -0,0 +1,19 @@
+##
+#
+class MiniTest::Unit::TestCase
+  # @yield
+  def assert_exists
+    begin
+      yield.blank?
+      # blank? if nothing found, kind_of Element otherwise
+    rescue AX::Element::SearchFailure => e
+      # problem somewhere in the path
+    end
+    assert_respond_to
+  end
+
+  def refute_exists
+  end
+end
+
+# @todo assertions for minitest/spec