AXElements 0.6.0beta2 → 0.7.5

data/lib/ax/element.rb

@@ -0,0 +1,518 @@
+# -*- coding: utf-8 -*-
+
+require 'ax_elements/vendor/inflector'
+require 'accessibility/enumerators'
+require 'accessibility/qualifier'
+require 'accessibility/errors'
+require 'accessibility/pp_inspector'
+require 'accessibility/factory'
+require 'accessibility/core'
+
+##
+# @abstract
+#
+# The abstract base class for all accessibility objects. This class
+# provides generic functionality that all accessibility objects require.
+class AX::Element
+  include Accessibility::PPInspector
+  include Accessibility::Factory
+
+  # @param [AXUIElementRef]
+  def initialize ref
+    @ref = ref
+  end
+
+
+  # @group Attributes
+
+  ##
+  # Cache of available attributes.
+  #
+  # @example
+  #
+  #   window.attributes # => [:size, :position, :title, ...]
+  #
+  # @return [Array<Symbol>]
+  def attributes
+    @attributes ||= TRANSLATOR.rubyize @ref.attributes
+  end
+
+  ##
+  # @todo Consider returning `nil` if the element does not have
+  #       the given attribute.
+  #
+  # Get the value of an attribute.
+  #
+  # @example
+  #
+  #   element.attribute :position # => #<CGPoint x=123.0 y=456.0>
+  #
+  # @param [#to_sym]
+  def attribute name
+    if rattr = lookup(name, @ref.attributes)
+      process @ref.attribute(rattr)
+    end
+  end
+
+  ##
+  # Needed to override inherited `NSObject#description`. If you want a
+  # description of the object then you should use {#inspect} instead.
+  def description
+    attribute :description
+  end
+
+  ##
+  # Return the `#size` of an attribute. This only works for attributes
+  # that are a collection. This exists because it is _much_ more
+  # efficient to find out how many `children` exist using this API
+  # instead of getting the children array and asking for the size.
+  #
+  # @example
+  #
+  #   table.size_of  :rows     # => 111
+  #   window.size_of :children # => 16
+  #
+  # @param [#to_sym]
+  # @return [Number]
+  def size_of attr
+    if rattr = lookup(attr, @ref.attributes)
+      @ref.size_of rattr
+    else
+      0
+    end
+  end
+
+  ##
+  # Get the process identifier for the application that the element
+  # belongs to.
+  #
+  # @example
+  #
+  #   element.pid # => 12345
+  #
+  # @return [Fixnum]
+  def pid
+    @ref.pid
+  end
+
+  ##
+  # Check whether or not an attribute is writable.
+  #
+  # @example
+  #
+  #   element.writable? :size  # => true
+  #   element.writable? :value # => false
+  #
+  # @param [#to_sym]
+  def writable? attr
+    if rattr = lookup(attr, @ref.attributes)
+      @ref.writable? rattr
+    else
+      false
+    end
+  end
+
+  ##
+  # Set a writable attribute on the element to the given value.
+  #
+  # @example
+  #
+  #   element.set :value, 'Hello, world!'
+  #   element.set :size,  [100, 200].to_size
+  #
+  # @param [#to_sym]
+  # @return the value that you were setting is returned
+  def set attr, value
+    unless writable? attr
+      raise NoMethodError, "#{attr} is read-only for #{inspect}"
+    end
+    value = value.relative_to(@ref.value.size) if value.kind_of? Range
+    rattr = lookup(attr, @ref.attributes)
+    @ref.set rattr, value
+    value
+  end
+
+
+  # @group Parameterized Attributes
+
+  ##
+  # List of available parameterized attributes. Most elements have no
+  # parameterized attributes, but the ones that do have many.
+  #
+  # @example
+  #
+  #   window.parameterized_attributes     # => []
+  #   text_field.parameterized_attributes # => [:string_for_range, :attributed_string, ...]
+  #
+  # @return [Array<Symbol>]
+  def parameterized_attributes
+    TRANSLATOR.rubyize @ref.parameterized_attributes
+  end
+
+  ##
+  # Get the value for a parameterized attribute.
+  #
+  # @example
+  #
+  #  text_field.attribute :string_for_range, for_param: (2..8).relative_to(10)
+  #
+  # @param [#to_sym]
+  def attribute attr, for_parameter: param
+    if rattr = lookup(attr, @ref.parameterized_attributes)
+      param = param.relative_to(@ref.value.size) if value.kind_of? Range
+      process @ref.attribute(rattr, for_parameter: param)
+    end
+  end
+
+
+  # @group Actions
+
+  ##
+  # List of available actions.
+  #
+  # @example
+  #
+  #   toolbar.actions # => []
+  #   button.actions  # => [:press]
+  #   menu.actions    # => [:open, :cancel]
+  #
+  # @return [Array<Symbol>]
+  def actions
+    TRANSLATOR.rubyize @ref.actions
+  end
+
+  ##
+  # Tell an object to trigger an action.
+  #
+  # For instance, you can tell a button to call the same method that
+  # would be called when pressing a button, except that the mouse will
+  # not move over to the button to press it, nor will the keyboard be
+  # used.
+  #
+  # @example
+  #
+  #   button.perform :press # => true
+  #
+  # @param [#to_sym]
+  # @return [Boolean] true if successful
+  def perform action
+    if raction = lookup(action, @ref.actions)
+      @ref.perform raction
+    else
+      false
+    end
+  end
+
+
+  # @group Search
+
+  ##
+  # Perform a breadth first search through the view hierarchy rooted at
+  # the current element.
+  #
+  # See the {file:docs/Searching.markdown Searching} tutorial for the
+  # details on searching.
+  #
+  # @example Find the dock icon for the Finder app
+  #
+  #   AX::DOCK.search( :application_dock_item, title:'Finder' )
+  #
+  # @param [#to_s]
+  # @param [Hash{Symbol=>Object}]
+  # @return [AX::Element,nil,Array<AX::Element>,Array<>]
+  def search kind, filters = {}, &block
+    kind      = kind.to_s
+    qualifier = Accessibility::Qualifier.new(kind, filters, &block)
+    tree      = Accessibility::Enumerators::BreadthFirst.new(self)
+
+    if TRANSLATOR.singularize(kind) == kind
+      tree.find { |element| qualifier.qualifies? element }
+    else
+      tree.find_all { |element| qualifier.qualifies? element }
+    end
+  end
+
+  ##
+  # Search for an ancestor of the current elemenet.
+  #
+  # As the opposite of {#search}, this also takes filters, and can
+  # be used to find a specific ancestor for the current element.
+  #
+  # @example
+  #
+  #   button.ancestor :window       # => #<AX::StandardWindow>
+  #   row.ancestor    :scroll_area  # => #<AX::ScrollArea>
+  #
+  # @param [#to_s]
+  # @param [Hash{Symbol=>Object}]
+  # @return [AX::Element]
+  def ancestor kind, filters = {}, &block
+    qualifier = Accessibility::Qualifier.new(kind, filters, &block)
+    element   = attribute :parent
+    until qualifier.qualifies? element
+      element = element.attribute :parent
+    end
+    element
+  end
+
+  ##
+  # We use {#method_missing} to dynamically handle requests to lookup
+  # attributes or search for elements in the view hierarchy. An attribute
+  # lookup is always tried first, followed by a parameterized attribute
+  # lookup, and then finally a search.
+  #
+  # Failing all lookups, this method calls `super`.
+  #
+  # @example
+  #
+  #   mail   = AX::Application.application_with_bundle_identifier 'com.apple.mail'
+  #
+  #   # attribute lookup
+  #   window = mail.focused_window
+  #   # is equivalent to
+  #   window = mail.attribute :focused_window
+  #
+  #   # parameterized attribute lookup
+  #   window.title_ui_element.string_for_range (1..10).relative_to(100)
+  #   # is equivalent to
+  #   title = window.attribute :title_ui_element
+  #   title.param_attribute :string_for_range, for_param: (1..10).relative_to(100)
+  #
+  #   # simple single element search
+  #   window.button # => You want the first Button that is found
+  #   # is equivalent to
+  #   window.search :button, {}
+  #
+  #   # simple multi-element search
+  #   window.buttons # => You want all the Button objects found
+  #   # is equivalent to
+  #   window.search :buttons, {}
+  #
+  #   # filters for a single element search
+  #   window.button(title: 'Log In') # => First Button with a title of 'Log In'
+  #   # is equivalent to
+  #   window.search :button, title: 'Log In'
+  #
+  #   # attribute and element search failure
+  #   window.application # => SearchFailure is raised
+  #
+  def method_missing method, *args, &block
+    if method[-1] == EQUALS
+      return set(method.chomp(EQUALS), args.first)
+
+    elsif attr = lookup(method, @ref.attributes)
+      return process @ref.attribute(attr)
+
+    elsif attr = lookup(method, @ref.parameterized_attributes)
+      return process @ref.attribute(attr, for_parameter: args.first)
+
+    elsif @ref.attributes.include? KAXChildrenAttribute
+      result = search method, *args, &block
+      return result unless result.blank?
+      raise Accessibility::SearchFailure.new(self, method, args.first)
+
+    else
+      super
+
+    end
+  end
+
+
+  # @group Notifications
+
+  def notifs
+    @notifs ||= {}
+  end
+
+  ##
+  # Register to receive notification of the given event being completed
+  # by the given element.
+  #
+  # {file:docs/Notifications.markdown Notifications} are a way to put
+  # non-polling delays into your scripts.
+  #
+  # Use this method to register to be notified of the specified event in
+  # an application.
+  #
+  # The block is optional. The block will be given the sender of the
+  # notification, which will almost always be `self`, and also the name
+  # of the notification being received. The block should return a
+  # boolean value that decides if the notification received is the
+  # expected one.
+  #
+  # @example
+  #
+  #   on_notification(:window_created) { |sender|
+  #     puts "#{sender.inspect} sent the ':window_created' notification"
+  #     true
+  #   }
+  #
+  # @param [#to_s] notif the name of the notification
+  # @yield Validate the notification; the block should return truthy if
+  #        the notification received is the expected one and the script can
+  #        stop waiting, otherwise should return falsy.
+  # @yieldparam [String] notif the name of the notification
+  # @yieldparam [AXUIElementRef] element the element that sent the notification
+  # @yieldreturn [Boolean]
+  # @return [Array(Observer, String, CFRunLoopSource)]
+  def on_notification name, &block
+    notif    = TRANSLATOR.guess_notification_for name
+    observer = @ref.observer &notif_callback_for(&block)
+    source   = @ref.run_loop_source_for observer
+    @ref.register observer, to_receive: notif
+    CFRunLoopAddSource(CFRunLoopGetCurrent(), source, KCFRunLoopDefaultMode)
+    notifs[name] = [observer, notif, source]
+  end
+
+  def unregister_notification name
+    unless notifs.has_key? name
+      raise ArgumentError, "You have no registrations for #{name}"
+    end
+    _unregister_notification *notifs.delete(name)
+  end
+
+  ##
+  # Cancel _all_ notification registrations for this object. Simple and
+  # clean, but a blunt tool at best. This will have to do for the time
+  # being...
+  #
+  # @return [nil]
+  def unregister_all
+    notifs.keys.each do |notif|
+      unregister_notification notif
+    end
+    nil
+  end
+
+  # @endgroup
+
+
+  ##
+  # Overriden to produce cleaner output.
+  #
+  # @return [String]
+  def inspect
+    msg  = "#<#{self.class}" << pp_identifier
+    attrs = @ref.attributes
+    msg << pp_position if attrs.include? KAXPositionAttribute
+    msg << pp_children if attrs.include? KAXChildrenAttribute
+    msg << pp_checkbox(:enabled) if attrs.include? KAXEnabledAttribute
+    msg << pp_checkbox(:focused) if attrs.include? KAXFocusedAttribute
+    msg << '>'
+  end
+
+  ##
+  # @note Since `#inspect` is often overridden by subclasses, this cannot
+  #       be an alias.
+  #
+  # An "alias" for {#inspect}.
+  #
+  # @return [String]
+  def to_s
+    inspect
+  end
+
+  ##
+  # Overriden to respond properly with regards to dynamic attribute
+  # lookups, but will return false for potential implicit searches.
+  def respond_to? name
+    lookup(name.chomp(EQUALS), @ref.attributes)               ||
+    lookup(name,               @ref.parameterized_attributes) ||
+    super
+  end
+
+  ##
+  # Get the center point of the element.
+  #
+  # @return [CGPoint]
+  def to_point
+    size     = attribute :size
+    point    = attribute :position
+    point.x += size.width  / 2
+    point.y += size.height / 2
+    point
+  end
+
+  ##
+  # Get the bounding rectangle for the element.
+  #
+  # @return [CGRect]
+  def bounds
+    point = attribute :position
+    size  = attribute :size
+    CGRectMake(*point, *size)
+  end
+
+  ##
+  # Get the application object for the element.
+  #
+  # @return [AX::Application]
+  def application
+    process @ref.application
+  end
+
+  ##
+  # Concept borrowed from `Active Support`. It is used during implicit
+  # searches to determine if searches yielded responses.
+  def blank?
+    false
+  end
+
+  ##
+  # @todo Need to add '?' to predicate methods, but how?
+  #
+  # Like {#respond_to?}, this is overriden to include attribute methods.
+  def methods include_super = true, include_objc_super = false
+    super.concat(attributes).concat(parameterized_attributes)
+  end
+
+  ##
+  # Overridden so that equality testing would work. A hack, but the only
+  # sane way I can think of to test for equivalency.
+  def == other
+    @ref == other.instance_variable_get(:@ref)
+  end
+  alias_method :eql?, :==
+  alias_method :equal?, :==
+
+
+  private
+
+  ##
+  # @private
+  #
+  # Performance hack.
+  #
+  # @return [String]
+  EQUALS = '='
+
+  def lookup key, values
+    value = TRANSLATOR.lookup key, values
+    return value if values.include? value
+  end
+
+  def notif_callback_for
+    # we are ignoring the context pointer since this is OO
+    Proc.new do |observer, sender, notif, _|
+      break unless yield(process sender) if block_given?
+      _unregister_notification observer, notif, run_loop_source_for(observer)
+      CFRunLoopStop(CFRunLoopGetCurrent())
+    end
+  end
+
+  ##
+  # @todo What are the implications of removing the run loop source?
+  #       Taking it out would clobber other notifications that are using
+  #       the same source, so we would have to check if we can remove it.
+  #
+  def _unregister_notification observer, notif, source
+    CFRunLoopRemoveSource(CFRunLoopGetCurrent(), source, KCFRunLoopDefaultMode)
+    @ref.unregister observer, from_receiving: notif
+  end
+
+end
+
+
+# Extensions so checking #blank? on search result "just works".
+class NSArray;  alias_method :blank?, :empty? end
+class NilClass; def blank?; true end end

data/lib/{ax_elements/elements → ax}/radio_button.rb

@@ -1,3 +1,5 @@
+require 'ax/element'
+
 ##
 # Radio buttons are not the same as a generic button, radio buttons work
 # in mutually exclusive groups (you can only select one at a time). You

data/lib/ax/row.rb

@@ -0,0 +1,37 @@
+require 'ax/element'
+require 'accessibility/qualifier'
+
+##
+# UI Element for the row in a table, outline, etc.
+class AX::Row < AX::Element
+
+  ##
+  # 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.
+  #
+  # This is useful for tables where it is difficult to identify which
+  # row item is the one you want based on the row items themselves.
+  # Often times the columns in the table will have identifying attributes,
+  # such as a header, and so you can use this method to figure out what
+  # column your row item is in and then the method will return the row
+  # item you wanted.
+  #
+  # @example
+  #
+  #   rows  = table.rows
+  #   total = rows.inject(0) { |sum, row|
+  #     sum += row.child_in_column(header: 'Price').value.to_i
+  #   }
+  #   puts "The average price is $ #{total / rows.size}"
+  #
+  # @param [Hash]
+  # @return [AX::Element]
+  def child_in_column filters, &block
+    qualifier = Accessibility::Qualifier.new(:Column, filters, &block)
+    column    = self.parent.columns.index { |x| qualifier.qualifies? x }
+    return self.children.at(column) if column
+    raise Accessibility::SearchFailure.new(self.parent, 'column', filters)
+  end
+
+end

data/lib/{ax_elements/elements → ax}/static_text.rb

@@ -1,3 +1,5 @@
+require 'ax/element'
+
 ##
 # Represents text on the screen that cannot directly be changed by
 # a user, usually a label or an instructional text block.

data/lib/ax/systemwide.rb

@@ -0,0 +1,86 @@
+require 'ax/element'
+require 'accessibility/string'
+
+##
+# Represents the special `SystemWide` accessibility object.
+#
+# Previously, this object was a singleton, but that apparently causes
+# problems with the AXAPIs. So you should always create a new instance
+# of the system wide object when you need to use it (even though they
+# are all the same thing).
+class AX::SystemWide < AX::Element
+  include Accessibility::String
+
+  ##
+  # Overridden since there is only one way to get the element ref.
+  def initialize
+    super AXUIElementCreateSystemWide()
+  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.
+  #
+  # See the {file:docs/KeyboardEvents.markdown Keyboard} documentation for
+  # more information on how to format strings.
+  #
+  # @return [Boolean]
+  def type_string string
+    @ref.post keyboard_events_for string
+    true
+  end
+
+  # @todo doc and cleanup
+  def keydown modifier
+    @ref.post [[EventGenerator::CUSTOM[modifier], true]]
+    true
+  end
+
+  # @todo doc and cleanup
+  def keyup modifier
+    @ref.post [[EventGenerator::CUSTOM[modifier], false]]
+    true
+  end
+
+  ##
+  # The system wide object cannot be used to perform searches. This method
+  # is just an override to avoid a difficult to understand error messages.
+  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
+
+  ##
+  # Find the element in at the given point for the topmost appilcation
+  # window.
+  #
+  # `nil` will be returned if there was nothing at that point.
+  #
+  # @param [#to_point]
+  # @return [AX::Element,nil]
+  def element_at point
+    process @ref.element_at point
+  end
+
+  ##
+  # Set the global messaging timeout. Searching through another interface
+  # and looking up attributes incurs a lot of IPC calls and sometimes an
+  # app is slow to respond.
+  #
+  # @param [Number]
+  # @return [Number]
+  def set_global_timeout seconds
+    @ref.set_timeout_to seconds
+  end
+
+end

data/lib/ax_elements/awesome_print.rb

@@ -0,0 +1,25 @@
+require 'awesome_print'
+
+module AwesomePrint::AXElements
+
+  def self.included base
+    base.send :alias_method, :cast_without_ax_elements, :cast
+    base.send :alias_method, :cast, :cast_with_ax_elements
+  end
+
+  def cast_with_ax_elements object, type
+    cast = cast_without_ax_elements object, type
+    cast = :ax_element if object.kind_of? ::AX::Element
+    cast
+  end
+
+
+  private
+
+  def awesome_ax_element object
+    object.inspect
+  end
+
+end
+
+AwesomePrint::Formatter.send :include, AwesomePrint::AXElements

data/lib/ax_elements/exception_workaround.rb

@@ -0,0 +1,8 @@
+##
+# Workaround for MacRuby ticket #1334
+class Exception
+  alias_method :original_message, :message
+  def message
+    "#{original_message}\n\t#{backtrace.join("\n\t")}"
+  end
+end