AXElements 0.6.0beta2 → 0.7.5

data/lib/accessibility/translator.rb

@@ -0,0 +1,178 @@
+require 'accessibility/version'
+require 'ax_elements/vendor/inflector'
+
+framework 'ApplicationServices'
+
+unless Object.const_defined? :KAXIdentifierAttribute
+  ##
+  # Added for backwards compatability with Snow Leopard.
+  # This attribute is standard with Lion and newer. AXElements depends
+  # on it being defined.
+  #
+  # @return [String]
+  KAXIdentifierAttribute = 'AXIdentifier'
+end
+
+
+##
+# Maintain all the rules for transforming Cocoa constants into something
+# a little more Rubyish.
+class Accessibility::Translator
+
+  def self.instance
+    @instance ||= new
+  end
+
+  ##
+  # Initialize the caches.
+  def initialize
+    init_unprefixes
+    init_normalizations
+    init_rubyisms
+    init_classifications
+    init_singularizations
+  end
+
+  ##
+  # @note In the case of a predicate name, this will strip the 'Is'
+  #       part of the name if it is present
+  #
+  # Takes an accessibility constant and returns a new string with the
+  # namespace prefix removed.
+  #
+  # @example
+  #
+  #   unprefix 'AXTitle'                    # => 'Title'
+  #   unprefix 'AXIsApplicationEnabled'     # => 'ApplicationEnabled'
+  #   unprefix 'MCAXEnabled'                # => 'Enabled'
+  #   unprefix KAXWindowCreatedNotification # => 'WindowCreated'
+  #   unprefix NSAccessibilityButtonRole    # => 'Button'
+  #
+  # @param [String]
+  # @return [String]
+  def unprefix key
+    @unprefixes[key]
+  end
+
+  ##
+  # Given a symbol, return the equivalent accessibility constant.
+  #
+  # @param [#to_sym]
+  # @param [Array<String>]
+  # @return [String]
+  def lookup key, values
+    @values = values
+    @rubyisms[key.to_sym]
+  end
+
+  # @return [Array<Symbol>]
+  def rubyize keys
+    keys.map { |x| @normalizations[x] }
+  end
+
+  ##
+  # Try to turn an arbitrary symbol into a notification constant, and
+  # then get the value of the constant.
+  #
+  # @param [#to_s]
+  # @return [String]
+  def guess_notification_for name
+    name  = name.to_s.gsub /(?:^|_)(.)/ do $1.upcase! || $1 end
+    const = "KAX#{name}Notification"
+    Object.const_defined?(const) ? Object.const_get(const) : name
+  end
+
+  ##
+  # Get the class name equivalent for a given symbol or string. This
+  # is just a caching front end to the `#classify` method from the
+  # ActiveSupport inflector.
+  #
+  # @example
+  #
+  #   classify 'text_field' # => "TextField"
+  #   classify 'buttons'    # => "Button"
+  #
+  # @param [String]
+  # @return [String]
+  def classify klass
+    @classifications[klass]
+  end
+
+  ##
+  # Get the singularized version of the word passed in. This is just
+  # a caching front end to the `#singularize` method from the
+  # ActiveSupport inflector.
+  #
+  # @example
+  #
+  #   singularize 'buttons'     # => 'button'
+  #   singularize 'check_boxes' # => 'check_box'
+  #
+  # @param [String]
+  # @return [String]
+  def singularize klass
+    @singularizations[klass]
+  end
+
+
+  private
+
+  # @return [Hash{String=>String}]
+  def init_unprefixes
+    @unprefixes = Hash.new do |hash, key|
+      hash[key] = key.sub /^[A-Z]*?AX(?:Is)?|\s+/, EMPTY_STRING
+    end
+  end
+
+  # @return [Hash{String=>Symbol}]
+  def init_normalizations
+    @normalizations = Hash.new do |hash, key|
+      hash[key] = Accessibility::Inflector.underscore(@unprefixes[key]).to_sym
+    end
+  end
+
+  # @return [Hash{Symbol=>String}]
+  def init_rubyisms
+    @rubyisms = Hash.new do |hash, key|
+      @values.each do |v| hash[@normalizations[v]] = v end
+      hash.fetch(key) do |k|
+        chomped_key = k.chomp(QUESTION_MARK).to_sym
+        chomped_val = hash.fetch(chomped_key, nil)
+        hash[key]   = chomped_val if chomped_val
+      end
+    end
+    # preload the table
+    @rubyisms[:id]          = KAXIdentifierAttribute
+    @rubyisms[:placeholder] = KAXPlaceholderValueAttribute
+  end
+
+  # @return [Hash{String=>String}]
+  def init_classifications
+    @classifications = Hash.new do |hash, key|
+      hash[key] = Accessibility::Inflector.classify(key)
+    end
+  end
+
+  # @return [Hash{String=>String}]
+  def init_singularizations
+    @singularizations = Hash.new do |hash, key|
+      hash[key] = Accessibility::Inflector.singularize(key)
+    end
+  end
+
+  ##
+  # @private
+  #
+  # Cached for performance.
+  #
+  # @return [String]
+  EMPTY_STRING = ''
+
+  ##
+  # @private
+  #
+  # Performance hack.
+  #
+  # @return [String]
+  QUESTION_MARK = '?'
+end

data/lib/accessibility/version.rb

@@ -0,0 +1,7 @@
+module Accessibility
+  # @return [String]
+  VERSION   = '0.7.5'
+
+  # @return [String]
+  CODE_NAME = 'Clefairy'
+end

data/lib/accessibility.rb

@@ -0,0 +1,79 @@
+require 'ax/application'
+
+##
+# The main AXElements namespace.
+module Accessibility
+class << self
+
+  # @group Finding an application object
+
+  ##
+  # @todo Move to {AX::Aplication#initialize} eventually.
+  # @todo Find a way for this method to work without sleeping;
+  #       consider looping begin/rescue/end until AX starts up
+  # @todo This needs to handle bad bundle identifier's gracefully
+  #
+  # This is the standard way of creating an application object. It will
+  # launch the app if it is not already running and then create the
+  # accessibility object.
+  #
+  # However, this method is a _HUGE_ hack in cases where the app is not
+  # already running; I've tried to register for notifications, launch
+  # synchronously, etc., but there is always a problem with accessibility
+  # not being ready.
+  #
+  # If this method fails to find an app with the appropriate bundle
+  # identifier then it will return nil, eventually.
+  #
+  # @example
+  #
+  #   application_with_bundle_identifier 'com.apple.mail' # wait a few seconds
+  #   application_with_bundle_identifier 'com.marketcircle.Daylite'
+  #
+  # @param [String] bundle a bundle identifier
+  # @return [AX::Application,nil]
+  def application_with_bundle_identifier bundle
+    10.times do
+      apps = NSRunningApplication.runningApplicationsWithBundleIdentifier bundle
+      return AX::Application.new(apps.first.processIdentifier) unless apps.empty?
+      launch_application bundle
+      sleep 2
+    end
+    nil
+  end
+
+  ##
+  # @deprecated Use {AX::Application.new} instead.
+  #
+  # Get the accessibility object for an application given its localized
+  # name. This will only work if the application is already running.
+  #
+  # @example
+  #
+  #   application_with_name 'Mail'
+  #
+  # @param [String] name name of the application to launch
+  # @return [AX::Application,nil]
+  def application_with_name name
+    AX::Application.new name
+  end
+
+  # @endgroup
+
+
+  private
+
+  ##
+  # Asynchronously launch an application given the bundle identifier.
+  #
+  # @param [String] bundle the bundle identifier for the app
+  # @return [Boolean]
+  def launch_application bundle
+    NSWorkspace.sharedWorkspace.launchAppWithBundleIdentifier bundle,
+                                                     options: NSWorkspaceLaunchAsync,
+                              additionalEventParamDescriptor: nil,
+                                            launchIdentifier: nil
+  end
+
+end
+end

data/lib/ax/application.rb

@@ -0,0 +1,234 @@
+require 'ax/element'
+require 'accessibility/string'
+
+##
+# Some additional constructors and conveniences for Application objects.
+#
+# As this class has evolved, it has gathered some functionality from
+# the `NSRunningApplication` class.
+class AX::Application < AX::Element
+  include Accessibility::String
+
+  ##
+  # Overridden so that we can also cache the `NSRunningApplication`
+  # instance for this object.
+  #
+  # You can initialize an application object with either the process
+  # identifier (pid) of the application, the name of the application,
+  # an `NSRunningApplication` instance for the application, or an
+  # accessibility (`AXUIElementRef`) token.
+  def initialize arg
+    case arg
+    when Fixnum
+      super SYSTEMWIDE.application_for arg
+      @app = NSRunningApplication.runningApplicationWithProcessIdentifier arg
+    when String
+      SYSTEMWIDE.spin_run_loop
+      @app = NSWorkspace.sharedWorkspace.runningApplications
+        .find { |app| app.localizedName == arg }
+      super SYSTEMWIDE.application_for @app.processIdentifier
+    when NSRunningApplication
+      super SYSTEMWIDE.application_for arg.processIdentifier
+      @app = arg
+    else
+      super arg # assume it is an AXUIElementRef
+      @app = NSRunningApplication.runningApplicationWithProcessIdentifier pid
+    end
+  end
+
+
+  # @group Attributes
+
+  ##
+  # Overridden to handle the {Accessibility::Language#set_focus} case.
+  #
+  # (see AX::Element#attribute)
+  def attribute attr
+    case attr
+    when :focused?, :focused then active?
+    when :hidden?,  :hidden  then hidden?
+    else
+      super
+    end
+  end
+
+  ##
+  # Ask the app whether or not it is the active app. This is equivalent
+  # to the dynamic #focused? method, but might make more sense to use
+  # in some cases.
+  def active?
+    @ref.spin_run_loop
+    @app.active?
+  end
+  alias_method :focused,  :active?
+  alias_method :focused?, :active?
+
+  ##
+  # Ask the app whether or not it is hidden.
+  def hidden?
+    @ref.spin_run_loop
+    @app.hidden?
+  end
+
+  ##
+  # Ask the app whether or not it is still running.
+  def terminated?
+    @ref.spin_run_loop
+    @app.terminated?
+  end
+
+  ##
+  # Overridden to handle the {Accessibility::Language#set_focus} case.
+  #
+  # (see AX::Element#set:to:)
+  def set attr, to: value
+    case attr
+    when :focused
+      perform(value ? :unhide : :hide)
+    when :active, :hidden
+      perform(value ? :hide : :unhide)
+    else
+      super
+    end
+  end
+
+
+  # @group Actions
+
+  ##
+  # Overridden to provide extra actions (e.g. `hide`, `terminate`).
+  #
+  # (see AX::Element#perform)
+  #
+  # @return [Boolean]
+  def perform name
+    case name
+    when :terminate
+      return true if terminated?
+      @app.terminate; sleep 0.2; terminated?
+    when :force_terminate
+      return true if terminated?
+      @app.forceTerminate; sleep 0.2; terminated?
+    when :hide
+      return true if hidden?
+      @app.hide; sleep 0.2; hidden?
+    when :unhide
+      return true if active?
+      @app.activateWithOptions(NSApplicationActivateIgnoringOtherApps)
+      sleep 0.2; active?
+    else
+      super
+    end
+  end
+
+  ##
+  # Send keyboard input to `self`, the control in the app that currently
+  # has focus will receive the key presses.
+  #
+  # For details on how to format the string, check out the
+  # {file:docs/KeyboardEvents.markdown Keyboard} documentation.
+  #
+  # @return [Boolean]
+  def type_string string
+    @ref.post keyboard_events_for string
+    true
+  end
+
+  # @todo doc and cleanup
+  def keydown key
+    @ref.post [[EventGenerator::CUSTOM[key], true]]
+    true
+  end
+
+  # @todo doc and cleanup
+  def keyup key
+    @ref.post [[EventGenerator::CUSTOM[key], false]]
+    true
+  end
+
+  # @return [AX::MenuItem]
+  def select_menu_item *path
+    target = navigate_menu *path
+    target.perform :press
+    target
+  end
+
+  # @return [AX::MenuItem]
+  def navigate_menu *path
+    perform :unhide # can't navigate menus unless the app is up front
+    current = attribute(:menu_bar).search(:menu_bar_item, title: path.shift)
+    path.each do |part|
+      current.perform :press
+      next_item = current.search(:menu_item, title: part)
+      if next_item.blank?
+        failure = Accessibility::SearchFailure.new(current, :menu_item, title: part)
+        current.perform :cancel # close menu
+        raise failure
+      else
+        current = next_item
+      end
+    end
+    current
+  end
+
+  ##
+  # Show the "About" window for the app. Returns the window that is
+  # opened.
+  #
+  # @return [AX::Window]
+  def show_about_window
+    windows = self.children.select { |x| x.kind_of? AX::Window }
+    select_menu_item self.title, /^About /
+    wait_for(:window, parent: self) { |window| !windows.include?(window) }
+  end
+
+  ##
+  # @note This method assumes that the app has setup the standard
+  #       CMD+, hotkey to open the pref window
+  #
+  # Try to open the preferences for the app. Returns the window that
+  # is opened.
+  #
+  # @return [AX::Window]
+  def show_preferences_window
+    windows = self.children.select { |x| x.kind_of? AX::Window }
+    type_string "\\COMMAND+,"
+    wait_for(:window, parent: self) { |window| !windows.include?(window) }
+  end
+
+  # @endgroup
+
+
+  ##
+  # @todo Include bundle identifier?
+  #
+  # Override the base class to make sure the pid is included.
+  def inspect
+    super.sub! />$/, "#{pp_checkbox(:focused)} pid=#{pid}>"
+  end
+
+  ##
+  # Find the element in `self` that is present at point given.
+  #
+  # `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
+
+  ##
+  # Get the bundle identifier for the application.
+  #
+  # @example
+  #
+  #   safari.bundle_identifier 'com.apple.safari'
+  #   daylite.bundle_identifier 'com.marketcircle.Daylite'
+  #
+  # @return [String]
+  def bundle_identifier
+    @app.bundleIdentifier
+  end
+
+end

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

@@ -1,3 +1,5 @@
+require 'ax/element'
+
 ##
 # A generic push button and the base class for most, but not all,
 # other buttons, including close buttons and sort buttons, but