AXElements 0.8.1 → 0.9.0

data/lib/ax/application.rb

@@ -11,32 +11,135 @@ require 'accessibility/string'
 class AX::Application < AX::Element
   include Accessibility::String
 
+  class << self
+    ##
+    # Asynchronously launch an application with given the bundle identifier
+    #
+    # @param bundle [String] bundle identifier for the app
+    # @return [Boolean]
+    def launch bundle
+      NSWorkspace.sharedWorkspace.launchAppWithBundleIdentifier bundle,
+                                                       options: NSWorkspace::NSWorkspaceLaunchAsync,
+                                additionalEventParamDescriptor: nil,
+                                              launchIdentifier: nil
+    end
+
+    ##
+    # Find and return the dock application
+    #
+    # @return [AX::Application]
+    def dock
+      new 'com.apple.dock'
+    end
+
+    ##
+    # Find and return the dock application
+    #
+    # @return [AX::Application]
+    def finder
+      new 'com.apple.finder'
+    end
+
+    ##
+    # Find and return the notification center UI app
+    #
+    # Obviously, this will only work on OS X 10.8+
+    #
+    # @return [AX::Application]
+    def notification_center
+      new 'com.apple.notificationcenterui'
+    end
+
+    ##
+    # Find and return the application which is frontmost
+    #
+    # This is often, but not necessarily, the same as the app that
+    # owns the menu bar.
+    #
+    # @return [AX::Application]
+    def frontmost_application
+      new NSWorkspace.sharedWorkspace.frontmostApplication
+    end
+    alias_method :frontmost_app, :frontmost_application
+
+    ##
+    # Find and return the application which owns the menu bar
+    #
+    # This is often, but not necessarily, the same as the app that
+    # is frontmost.
+    #
+    # @return [AX::Application]
+    def menu_bar_owner
+      new NSWorkspace.sharedWorkspace.menuBarOwningApplication
+    end
+  end
+
   ##
-  # Overridden so that we can more flexibly manipulate input.
+  # Standard way of creating a new application 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.
   #
-  # @param [Number,String,NSRunningApplication]
+  # Given a PID, we try to lookup the application and wrap it.
+  #
+  # Given an `NSRunningApplication` instance, we simply wrap it.
+  #
+  # Given a string we do some complicated magic to try and figure out if
+  # the string is a bundle identifier or the localized name of the
+  # application. Given a bundle identifier we try to launch the app if
+  # it is not already running, given a localized name we search the running
+  # applications for the app. We wrap what we get back if we get anything
+  # back.
+  #
+  # Note however, given a bundle identifier to launch the application our
+  # implementation is a bit of a hack; I've tried to register for
+  # notifications, launch synchronously, etc., but there is always a problem
+  # with accessibility not being ready right away, so we will poll the app
+  # to see when it is ready with a timeout of ~10 seconds.
+  #
+  # If this method fails to find an app then an exception will be raised.
+  #
+  # @example
+  #
+  #   AX::Application.new 'com.apple.mail'
+  #   AX::Application.new 'Mail'
+  #   AX::Application.new 43567
+  #
+  # @param arg [Number,String,NSRunningApplication]
   def initialize arg
     case arg
     when Fixnum
-      super SYSTEMWIDE.application_for arg
+      super Accessibility::Element.application_for arg
       @app = NSRunningApplication.runningApplicationWithProcessIdentifier arg
     when String
-      @app =
-        NSRunningApplication.runningApplicationsWithBundleIdentifier(arg).first ||
-        (
-          SYSTEMWIDE.spin_run_loop
-          NSWorkspace.sharedWorkspace.runningApplications.find { |app|
-            app.localizedName == arg
-          }
+      until @app
+        @app =
+         (
+          app = NSRunningApplication.runningApplicationsWithBundleIdentifier arg
+          app.first
+
+         ) || (
+           spin
+           NSWorkspace.sharedWorkspace.runningApplications.find { |app|
+             app.localizedName == arg
+           }
+
+         ) || (
+           count ||= 0
+           if AX::Application.launch arg
+             spin 1
+             count += 1
+             raise "#{arg} failed to launch in time" if count == 10
+           else
+             raise "#{arg} is not a registered bundle identifier for the system"
+           end
         )
-      super SYSTEMWIDE.application_for @app.processIdentifier
+      end
+      super Accessibility::Element.application_for @app.processIdentifier
     when NSRunningApplication
-      super SYSTEMWIDE.application_for arg.processIdentifier
+      super Accessibility::Element.application_for arg.processIdentifier
       @app = arg
     else
       super arg # assume it is an AXUIElementRef
@@ -47,9 +150,6 @@ class AX::Application < AX::Element
 
   # @group Attributes
 
-  ##
-  # Overridden to handle the {Accessibility::DSL#set_focus_to} case.
-  #
   # (see AX::Element#attribute)
   def attribute attr
     case attr
@@ -59,8 +159,7 @@ class AX::Application < AX::Element
     end
   end
 
-  ##
-  # Overridden to handle the {Accessibility::DSL#set_focus_to} case.
+  # (see AX::Element#writable?)
   def writable? attr
     case attr
     when :focused?, :focused, :hidden?, :hidden then true
@@ -73,7 +172,7 @@ class AX::Application < AX::Element
   # to the dynamic `#focused?` method, but might make more sense to use
   # in some cases.
   def active?
-    @ref.spin_run_loop
+    spin
     @app.active?
   end
   alias_method :focused,  :active?
@@ -82,20 +181,17 @@ class AX::Application < AX::Element
   ##
   # Ask the app whether or not it is hidden.
   def hidden?
-    @ref.spin_run_loop
+    spin
     @app.hidden?
   end
 
   ##
   # Ask the app whether or not it is still running.
   def terminated?
-    @ref.spin_run_loop
+    spin
     @app.terminated?
   end
 
-  ##
-  # Overridden to handle the {Accessibility::Language#set_focus} case.
-  #
   # (see AX::Element#set)
   def set attr, value
     case attr
@@ -108,30 +204,105 @@ class AX::Application < AX::Element
     end
   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
+
+  ##
+  # 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
+
 
   # @group Actions
 
   ##
-  # Overridden to provide extra actions (e.g. `hide`, `terminate`).
+  # @note This is often async and may return before the action is completed
   #
-  # (see AX::Element#perform)
+  # Ask the app to quit
+  #
+  # @return [Boolean]
+  def terminate
+    perform :terminate
+  end
+
+  ##
+  # @note This is often async and may return before the action is completed
+  #
+  # Force the app to quit
   #
   # @return [Boolean]
+  def terminate!
+    perform :force_terminate
+  end
+
+  ##
+  # @note This is often async and may return before the action is completed
+  #
+  # Ask the app to hide itself
+  #
+  # @return [Boolean]
+  def hide
+    perform :hide
+  end
+
+  ##
+  # @note This is often async and may return before the action is completed
+  #
+  # As the app to unhide itself and bring to front
+  #
+  # @return [Boolean]
+  def unhide
+    perform :unhide
+  end
+
+  # (see AX::Element#perform)
   def perform name
     case name
     when :terminate
       return true if terminated?
-      @app.terminate; sleep 0.2; terminated?
+      @app.terminate; spin 0.25; terminated?
     when :force_terminate
       return true if terminated?
-      @app.forceTerminate; sleep 0.2; terminated?
+      @app.forceTerminate; spin 0.25; terminated?
     when :hide
       return true if hidden?
-      @app.hide; sleep 0.2; hidden?
+      @app.hide; spin 0.25; hidden?
     when :unhide
       return true if active?
-      @app.activateWithOptions(NSApplicationActivateIgnoringOtherApps)
-      sleep 0.2; active?
+      @app.activateWithOptions(NSRunningApplication::NSApplicationActivateIgnoringOtherApps)
+      spin 0.25; active?
     else
       super
     end
@@ -144,6 +315,7 @@ class AX::Application < AX::Element
   # For details on how to format the string, check out the
   # [Keyboarding documentation](http://github.com/Marketcircle/AXElements/wiki/Keyboarding).
   #
+  # @param string [String]
   # @return [Boolean]
   def type string
     @ref.post keyboard_events_for string
@@ -161,7 +333,7 @@ class AX::Application < AX::Element
   #     drag_mouse_to point
   #   end
   #
-  # @param [String]
+  # @param key [String]
   # @return [Number,nil]
   def hold_modifier key
     code = EventGenerator::CUSTOM[key]
@@ -182,6 +354,7 @@ class AX::Application < AX::Element
   #
   #   safari.select_menu_item 'Edit', 'Find', /Google/
   #
+  # @param path [String,Regexp]
   # @return [AX::MenuItem]
   def select_menu_item *path
     target = navigate_menu *path
@@ -195,6 +368,7 @@ class AX::Application < AX::Element
   #
   # You may also be interested in {#select_menu_item}.
   #
+  # @param path [String,Regexp]
   # @return [AX::MenuItem]
   def navigate_menu *path
     perform :unhide # can't navigate menus unless the app is up front
@@ -249,50 +423,10 @@ class AX::Application < AX::Element
   #
   # `nil` will be returned if there was nothing at that point.
   #
-  # @param [#to_point]
+  # @param point [#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
-
-  ##
-  # 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'
+    @ref.element_at(point).to_ruby
   end
 
 
@@ -303,8 +437,4 @@ class AX::Application < AX::Element
     @bundle ||= NSBundle.bundleWithURL @app.bundleURL
   end
 
-  # @private
-  # @return [AXUIElementRef]
-  SYSTEMWIDE = AXUIElementCreateSystemWide()
-
 end

data/lib/ax/element.rb

@@ -1,28 +1,28 @@
 # -*- coding: utf-8 -*-
 
+require 'active_support/core_ext/object/blank'
 require 'accessibility/core'
 require 'accessibility/factory'
 require 'accessibility/translator'
 require 'accessibility/enumerators'
 require 'accessibility/qualifier'
 require 'accessibility/errors'
-require 'accessibility/pp_inspector'
+require 'accessibility/pretty_printer'
+
 
 ##
 # @abstract
 #
 # The abstract base class for all accessibility objects. `AX::Element`
-# composes low level `AXUIElementRef` objects into a more Rubyish
+# composes low level {AXUIElementRef} objects into a more Rubyish
 # interface.
 #
 # This abstract base class provides generic functionality that all
 # accessibility objects require.
 class AX::Element
-  include Accessibility::PPInspector
-  include Accessibility::Factory
-
+  include Accessibility::PrettyPrinter
 
-  # @param [AXUIElementRef]
+  # @param ref [AXUIElementRef]
   def initialize ref
     @ref = ref
   end
@@ -44,18 +44,18 @@ class AX::Element
 
   ##
   # Get the value of an attribute. This method will return `nil` if
-  # the attribute does not have a value, if the element does not have
-  # the attribute, or if the element is dead. There is an execption
-  # for the `:children` attribute which is always guaranteed to return
-  # an array.
+  # the attribute does not have a value or if the element is dead. The
+  # execption to the rule is that the `:children` attribute will always
+  # return an array unless the element does not have the `:children`
+  # attribute.
   #
   # @example
   #
   #   element.attribute :position # => #<CGPoint x=123.0 y=456.0>
   #
-  # @param [#to_sym]
+  # @param attr [#to_sym]
   def attribute attr
-    process @ref.attribute TRANSLATOR.cocoaify attr
+    @ref.attribute(TRANSLATOR.cocoaify(attr)).to_ruby
   end
 
   ##
@@ -66,21 +66,20 @@ class AX::Element
   #
   # @return [String]
   def description
-    attribute :description
+    attribute(:description).to_ruby
   end
 
   ##
-  # Fetch the children elements for the current element. If the current
-  # element does not have children then an empty array will be returned.
+  # Fetch the children elements for the current element.
   #
   # @return [Array<AX::Element>]
   def children
-    attribute :children
+    @ref.children.to_ruby
   end
 
   ##
   # Get a list of elements, starting with the receiver and riding
-  # the hierarchy up to the top level object (i.e. the {AX::Application}).
+  # the hierarchy up to the top level object (i.e. the {AX::Application})
   #
   # @example
   #
@@ -89,15 +88,16 @@ class AX::Element
   #     # => [#<AX::ApplicationDockItem...>, #<AX::List...>, #<AX::Application...>]
   #
   # @return [Array<AX::Element>]
-  def ancestry *elements
-    elements = [self] if elements.empty?
+  def ancestry elements = self
+    elements = Array(elements)
     element  = elements.last
     if element.attributes.include? :parent
-      ancestry(elements << element.parent)
+      ancestry(elements << element.attribute(:parent))
     else
       elements
     end
   end
+  alias_method :lineage, :ancestry
 
   ##
   # Get the process identifier for the application that the element
@@ -123,7 +123,7 @@ class AX::Element
   #   table.size_of  :rows     # => 111
   #   window.size_of :children # => 16
   #
-  # @param [#to_sym]
+  # @param attr [#to_sym]
   # @return [Number]
   def size_of attr
     @ref.size_of TRANSLATOR.cocoaify attr
@@ -137,7 +137,7 @@ class AX::Element
   #   element.writable? :size  # => true
   #   element.writable? :value # => false
   #
-  # @param [#to_sym]
+  # @param attr [#to_sym]
   def writable? attr
     @ref.writable? TRANSLATOR.cocoaify attr
   end
@@ -150,7 +150,7 @@ class AX::Element
   #   element.set :value, 'Hello, world!'
   #   element.set :size,  [100, 200].to_size
   #
-  # @param [#to_sym]
+  # @param attr [#to_sym]
   # @return the value that you were setting is returned
   def set attr, value
     unless writable? attr
@@ -184,10 +184,11 @@ class AX::Element
   #
   #  text_field.parameterized_attribute :string_for_range, 2..8
   #
-  # @param [#to_sym]
+  # @param attr [#to_sym]
+  # @param param [Object]
   def parameterized_attribute attr, param
-    param = param.relative_to(@ref.value.size) if value.kind_of? Range
-    process @ref.parameterized_attribute(TRANSLATOR.cocoaify(attr), param)
+    param = param.relative_to(@ref.value.size) if param.kind_of? Range
+    @ref.parameterized_attribute(TRANSLATOR.cocoaify(attr), param).to_ruby
   end
 
 
@@ -220,7 +221,7 @@ class AX::Element
   #   button.perform :press    # => true
   #   button.perform :make_pie # => false
   #
-  # @param [#to_sym]
+  # @param action [#to_sym]
   # @return [Boolean] true if successful
   def perform action
     @ref.perform TRANSLATOR.cocoaify action
@@ -234,15 +235,16 @@ class AX::Element
   # the current element. If you are concerned about the return value of
   # this method, you can call {#blank?} on the return object.
   #
-  # See the [Searching Tutorial](http://github.com/Marketcircle/AXElements/wiki/Searching)
+  # See the [Searching wiki](http://github.com/Marketcircle/AXElements/wiki/Searching)
   # for the details on search semantics.
   #
   # @example Find the dock icon for the Finder app
   #
   #   AX::DOCK.search(:application_dock_item, title:'Finder')
   #
-  # @param [#to_s]
-  # @param [Hash{Symbol=>Object}]
+  # @param kind [#to_s]
+  # @param filters [Hash{Symbol=>Object}]
+  # @yield Optional block used for filtering
   # @return [AX::Element,nil,Array<AX::Element>,Array<>]
   def search kind, filters = {}, &block
     kind      = kind.to_s
@@ -262,19 +264,23 @@ class AX::Element
   # As the opposite of {#search}, this also takes filters, and can
   # be used to find a specific ancestor for the current element.
   #
+  # Returns `nil` if no ancestor is found.
+  #
   # @example
   #
   #   button.ancestor :window       # => #<AX::StandardWindow>
   #   row.ancestor    :scroll_area  # => #<AX::ScrollArea>
   #
-  # @param [#to_s]
-  # @param [Hash{Symbol=>Object}]
-  # @return [AX::Element]
+  # @param kind [#to_s]
+  # @param filters [Hash{Symbol=>Object}]
+  # @yield Optional block used for search filtering
+  # @return [AX::Element,nil]
   def ancestor kind, filters = {}, &block
     qualifier = Accessibility::Qualifier.new(kind, filters, &block)
-    element   = attribute :parent
+    element   = self
     until qualifier.qualifies? element
       element = element.attribute :parent
+      return nil unless element
     end
     element
   end
@@ -336,7 +342,7 @@ class AX::Element
       return attribute(method)
 
     elsif @ref.parameterized_attributes.include? key
-      return paramaterized_attribute(method, args.first)
+      return parameterized_attribute(method, args.first)
 
     elsif @ref.attributes.include? KAXChildrenAttribute
       if (result = search(method, *args, &block)).blank?
@@ -359,7 +365,7 @@ class AX::Element
   #
   # @return [String]
   def inspect
-    msg  = "#<#{self.class}" << pp_identifier
+    msg  = "#<#{self.class}" << pp_identifier.to_s
     msg << pp_position if attributes.include? :position
     msg << pp_children if attributes.include? :children
     msg << pp_checkbox(:enabled) if attributes.include? :enabled
@@ -429,14 +435,14 @@ class AX::Element
   def bounds
     CGRect.new(attribute(:position), attribute(:size))
   end
-  alias_method :rect, :bounds
+  alias_method :to_rect, :bounds
 
   ##
   # Get the application object for the element.
   #
   # @return [AX::Application]
   def application
-    process @ref.application
+    @ref.application.to_ruby
   end
 
   # (see NilClass#blank?)
@@ -448,16 +454,24 @@ class AX::Element
   # Return whether or not the receiver is "dead".
   #
   # A dead element is one that is no longer in the app's view
-  # hierarchy, which is not necessarily related to visibility.
+  # hierarchy. This is not directly related to visibility, but an
+  # element that is invalid will not be visible, but an invisible
+  # element might not be invalid.
   def invalid?
-    @ref.role.nil?
+    @ref.invalid?
   end
 
-  ##
-  # Like {#respond_to?}, this is overriden to include attribute methods.
-  # Though, it does include dynamic predicate methods at the moment.
-  def methods include_super = true, include_objc_super = false
-    super.concat(attributes).concat(parameterized_attributes)
+  if on_macruby?
+    ##
+    # Like {#respond_to?}, this is overriden to include attribute methods.
+    # Though, it does include dynamic predicate methods at the moment.
+    def methods include_super = true, include_objc_super = false
+      super.concat(attributes).concat(parameterized_attributes)
+    end
+  else
+    def methods include_super = true
+      super.concat(attributes).concat(parameterized_attributes)
+    end
   end
 
   ##
@@ -477,25 +491,8 @@ class AX::Element
   # @return [String]
   EQUALS = '='
 
-end
-
-
-# Extensions so checking `#blank?` on search result "just works".
-class NSArray
-  # (see NilClass#blank?)
-  alias_method :blank?, :empty?
-end
+  # @private
+  # @return [Accessibility::Translator]
+  TRANSLATOR = Accessibility::Translator.instance
 
-# Extensions so checking `#blank?` on search result "just works".
-class NilClass
-  ##
-  # Whether or not the object is "blank". The concept of blankness
-  # borrowed from `Active Support` and is true if the object is falsey
-  # or `#empty?`.
-  #
-  # This method is used by implicit searching in AXElements to
-  # determine if searches yielded responses.
-  def blank?
-    true
-  end
 end