AXElements 0.7.8 → 0.8.0

data/lib/accessibility.rb

@@ -1,29 +1,41 @@
+require 'accessibility/version'
 require 'ax/application'
 
-##
-# The main AXElements namespace.
-module Accessibility
-class << self
+class << Accessibility
+
+  # Initialize the DEBUG value
+  @debug = ENV.fetch 'AXDEBUG', $DEBUG
+
+  ##
+  # Whether or not to turn on DEBUG features in AXElements. The
+  # value is initially inherited from `$DEBUG` but can be overridden
+  # by an environment variable named `AXDEBUG` or changed dynamically
+  # at runtime.
+  #
+  # @return [Boolean]
+  attr_accessor :debug
+  alias_method :debug?, :debug
+
 
   # @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
+  # However, this method is a bit of a 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.
+  # not being ready right away.
   #
   # If this method fails to find an app with the appropriate bundle
-  # identifier then it will return nil, eventually.
+  # identifier then it will raise an exception. If the problem was not a
+  # typo, then it might mean that the bundle identifier has not been
+  # registered with the system yet and you should launch the app once
+  # manually.
   #
   # @example
   #
@@ -33,17 +45,20 @@ class << self
   # @param [String] bundle a bundle identifier
   # @return [AX::Application,nil]
   def application_with_bundle_identifier bundle
-    10.times do
-      app = NSRunningApplication.runningApplicationsWithBundleIdentifier(bundle).first
-      return AX::Application.new(app) if app
-      launch_application bundle
-      sleep 2
+    if app_running?(bundle) || launch_application(bundle)
+      10.times do
+        return AX::Application.new(bundle) if app_running? bundle
+        sleep 1
+      end
+    else
+      raise ArgumentError "Could not launch app matching bundle id `#{bundle}'"
     end
     nil
   end
 
   ##
-  # @deprecated Use {AX::Application.new} instead.
+  # @deprecated Directly initialize an {AX::Application} instance instead
+  #             (e.g. `AX::Application.new('Terminal')`).
   #
   # Get the accessibility object for an application given its localized
   # name. This will only work if the application is already running.
@@ -55,6 +70,7 @@ class << self
   # @param [String] name name of the application to launch
   # @return [AX::Application,nil]
   def application_with_name name
+    $stderr.puts 'DEPRECATED: Use AX::Application.new instead'
     AX::Application.new name
   end
 
@@ -63,6 +79,16 @@ class << self
 
   private
 
+  ##
+  # Find out if the app is running and if so, return the running application
+  # for that bundle.
+  #
+  # @param [String]
+  # @return [NSRunningApplication,nil]
+  def app_running? bundle
+    NSRunningApplication.runningApplicationsWithBundleIdentifier(bundle).first
+  end
+
   ##
   # Asynchronously launch an application given the bundle identifier.
   #
@@ -76,4 +102,3 @@ class << self
   end
 
 end
-end

data/lib/ax/application.rb

@@ -2,28 +2,24 @@ require 'ax/element'
 require 'accessibility/string'
 
 ##
-# Some additional constructors and conveniences for Application objects.
+# The accessibility object representing the running application. This
+# class contains some additional constructors and conveniences for
+# Application objects.
 #
 # As this class has evolved, it has gathered some functionality from
-# the `NSRunningApplication` class.
+# the `NSRunningApplication` and `NSBundle` classes.
 class AX::Application < AX::Element
   include Accessibility::String
 
   ##
-  # @private
-  # Cached reference to the system wide object.
-  #
-  # @return [AXUIElementRef]
-  SYSTEMWIDE = AXUIElementCreateSystemWide()
-
-  ##
-  # Overridden so that we can also cache the `NSRunningApplication`
-  # instance for this object.
+  # Overridden so that we can more flexibly manipulate input.
   #
   # 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.
+  #
+  # @param [Number,String,NSRunningApplication]
   def initialize arg
     case arg
     when Fixnum
@@ -52,7 +48,7 @@ class AX::Application < AX::Element
   # @group Attributes
 
   ##
-  # Overridden to handle the {Accessibility::DSL#set_focus} case.
+  # Overridden to handle the {Accessibility::DSL#set_focus_to} case.
   #
   # (see AX::Element#attribute)
   def attribute attr
@@ -74,7 +70,7 @@ class AX::Application < AX::Element
 
   ##
   # 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
+  # to the dynamic `#focused?` method, but might make more sense to use
   # in some cases.
   def active?
     @ref.spin_run_loop
@@ -100,7 +96,7 @@ class AX::Application < AX::Element
   ##
   # Overridden to handle the {Accessibility::Language#set_focus} case.
   #
-  # (see AX::Element#set:to:)
+  # (see AX::Element#set)
   def set attr, value
     case attr
     when :focused
@@ -142,30 +138,50 @@ class AX::Application < AX::Element
   end
 
   ##
-  # Send keyboard input to `self`, the control in the app that currently
-  # has focus will receive the key presses.
+  # Send keyboard input to the receiver, 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.
+  # [Keyboarding documentation](http://github.com/Marketcircle/AXElements/wiki/Keyboarding).
   #
   # @return [Boolean]
   def type string
     @ref.post keyboard_events_for string
     true
   end
+  alias_method :type_string, :type
 
-  # @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
+  ##
+  # Press the given modifier key and hold it down while yielding to
+  # the given block.
+  #
+  # @example
+  #
+  #   hold_key "\\CONTROL" do
+  #     drag_mouse_to point
+  #   end
+  #
+  # @param [String]
+  # @return [Number,nil]
+  def hold_modifier key
+    code = EventGenerator::CUSTOM[key]
+    raise ArgumentError, "Invalid modifier `#{key}' given" unless code
+    @ref.post [[code, true]]
+    yield
+  ensure
+    @ref.post [[code,false]] if code
+    code
   end
 
+  ##
+  # Navigate the menu bar menus for the receiver and select the menu
+  # item at the end of the given path. This method will open each menu
+  # in the path.
+  #
+  # @example
+  #
+  #   safari.select_menu_item 'Edit', 'Find', /Google/
+  #
   # @return [AX::MenuItem]
   def select_menu_item *path
     target = navigate_menu *path
@@ -173,8 +189,15 @@ class AX::Application < AX::Element
     target
   end
 
+  ##
+  # Navigate the menu bar menus for the receiver. This method will not
+  # select the last item, but it will open each menu along the path.
+  #
+  # You may also be interested in {#select_menu_item}.
+  #
   # @return [AX::MenuItem]
   def navigate_menu *path
+    # @todo CLEAN UP
     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|
@@ -220,15 +243,13 @@ class AX::Application < AX::Element
 
 
   ##
-  # @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.
+  # Find the element in the receiver that is at point given.
   #
   # `nil` will be returned if there was nothing at that point.
   #
@@ -251,4 +272,43 @@ class AX::Application < AX::Element
     @app.bundleIdentifier
   end
 
+  ##
+  # Return the `Info.plist` data for the application. This is a plist
+  # file that all bundles in OS X must contain.
+  #
+  # Many bits of metadata are stored in the plist, check the
+  # [reference](https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/ConfigFiles.html)
+  # for more details.
+  #
+  # @return [Hash]
+  def info_plist
+    bundle.infoDictionary
+  end
+
+  ##
+  # Get the version string for the application.
+  #
+  # @example
+  #
+  #   AX::Application.new("Safari").version    # => "5.2"
+  #   AX::Application.new("Terminal").version  # => "2.2.2"
+  #   AX::Application.new("Daylite").version   # => "3.15 (build 3664)"
+  #
+  # @return [String]
+  def version
+    bundle.objectForInfoDictionaryKey 'CFBundleShortVersionString'
+  end
+
+
+  private
+
+  # @return [NSBundle]
+  def bundle
+    @bundle ||= NSBundle.bundleWithURL @app.bundleURL
+  end
+
+  # @private
+  # @return [AXUIElementRef]
+  SYSTEMWIDE = AXUIElementCreateSystemWide()
+
 end

data/lib/ax/button.rb

@@ -13,8 +13,11 @@ class AX::Button < AX::Element
   #
   # @return [Boolean]
   def == other
-    return super unless other.kind_of? NSString
-    return attribute(:title) == other
+    if other.kind_of? NSString
+      attribute(:title) == other
+    else
+      super
+    end
   end
 
 end