AXElements 0.7.8 → 0.8.0

data/lib/accessibility/core.rb

@@ -31,8 +31,9 @@ require 'accessibility/version'
 #       still work out ok.
 # @todo I feel a bit weird having to instantiate a new pointer every
 #       time I want to fetch an attribute. Since allocations are costly,
-#       it hurts performance a lot when it comes to searches. I wonder if
-#       it would pay off to have a pool of pointers...
+#       and searching requires _many_ AXAPI calls, it hurts performance
+#       a lot when it comes to searches. I wonder if it would pay off
+#       to have a pool of pointers...
 #
 # Core abstraction layer that that interacts with OS X Accessibility
 # APIs (AXAPI). This is actually just a mixin for `AXUIElementRef` objects
@@ -85,8 +86,11 @@ module Accessibility::Core
   # will be unwrapped for you, if you expect to get a {CFRange} you
   # will be given a {Range} instead.
   #
-  # As a convention, if the backing element is no longer alive then
-  # you will receive `nil` for any attribute.
+  # As a convention, if the backing element is no longer alive, or
+  # the attribute does not exist, or a system failure occurs then
+  # you will receive `nil` for any attribute except for
+  # `KAXChildrenAttribute`. `KAXChildrenAttribute` will always return
+  # an array.
   #
   # @example
   #   attribute KAXTitleAttribute   # => "HotCocoa Demo"
@@ -94,14 +98,15 @@ module Accessibility::Core
   #   attribute KAXParentAttribute  # => #<AXUIElementRef>
   #   attribute KAXNoValueAttribute # => nil
   #
-  # @param [String] name an attribute constant
+  # @param [String]
   def attribute name
     ptr = Pointer.new :id
     case code = AXUIElementCopyAttributeValue(self, name, ptr)
     when 0
       ptr.value.to_ruby
     when KAXErrorNoValue, KAXErrorAttributeUnsupported,
-         KAXErrorFailure, KAXErrorInvalidUIElement then
+         KAXErrorFailure, KAXErrorInvalidUIElement,
+                          KAXErrorIllegalArgument then
       name == KAXChildrenAttribute ? [] : nil
     else
       handle_error code, name
@@ -109,13 +114,14 @@ module Accessibility::Core
   end
 
   ##
-  # Shortcut for getting the `KAXRoleAttribute`.
+  # Shortcut for getting the `KAXRoleAttribute`. Remember that
+  # dead elements may return `nil` for their role.
   #
   # @example
   #
   #   role  # => KAXWindowRole
   #
-  # @return [String]
+  # @return [String,nil]
   def role
     attribute KAXRoleAttribute
   end
@@ -136,7 +142,9 @@ module Accessibility::Core
   end
 
   ##
-  # Shortcut for getting the `KAXChildrenAttribute`.
+  # Shortcut for getting the `KAXChildrenAttribute`. This is guaranteed
+  # to alwayl return an array or raise an exception, unless the object
+  # you are querying is behaving maliciously.
   #
   # @example
   #
@@ -159,6 +167,33 @@ module Accessibility::Core
     attribute KAXValueAttribute
   end
 
+  ##
+  # Get the process identifier (PID) of the application that the element
+  # belongs to.
+  #
+  # This method will return `0` if the element is dead or if the receiver
+  # is the the system wide element.
+  #
+  # @example
+  #
+  #   pid              # => 12345
+  #   system_wide.pid  # => 0
+  #
+  # @return [Fixnum]
+  def pid
+    @pid ||= (
+      ptr = Pointer.new :int
+      case code = AXUIElementGetPid(self, ptr)
+      when 0
+        ptr.value
+      when KAXErrorInvalidUIElement
+        self == system_wide ? 0 : handle_error(code)
+      else
+        handle_error code
+      end
+      )
+  end
+
   ##
   # Get the size of the array for attributes that would return an array.
   # When performance matters, this is much faster than getting the array
@@ -172,7 +207,7 @@ module Accessibility::Core
   #   size_of KAXChildrenAttribute  # => 19
   #   size_of KAXRowsAttribute      # => 100
   #
-  # @param [String] name an attribute constant
+  # @param [String]
   # @return [Number]
   def size_of name
     ptr = Pointer.new :long_long
@@ -188,14 +223,18 @@ module Accessibility::Core
   end
 
   ##
-  # Returns whether or not an attribute is writable.
+  # Returns whether or not an attribute is writable. You should check
+  # writability before trying call {#set} for the attribute.
+  #
+  # In case of internal error or if the element dies, this method will
+  # return `false`.
   #
   # @example
   #
   #   writable? KAXSizeAttribute  # => true
   #   writable? KAXTitleAttribute # => false
   #
-  # @param [String] name an attribute constant
+  # @param [String]
   def writable? name
     ptr = Pointer.new :bool
     case code = AXUIElementIsAttributeSettable(self, name, ptr)
@@ -210,24 +249,24 @@ module Accessibility::Core
   end
 
   ##
-  # @note This method does not check writability of the attribute
-  #       you are setting. If you need to check, use {#writable?}
-  #       first.
-  #
-  # Set the given value to the given attribute. You do not need to
+  # Set the given value for the given attribute. You do not need to
   # worry about wrapping objects first, `Range` objects will also
   # be automatically converted into `CFRange` objects and then
   # wrapped.
   #
-  # Unlike when reading attributes, writing to a dead element will
-  # raise an exception.
+  # This method does not check writability of the attribute you are
+  # setting. If you need to check, use {#writable?} first to check.
+  #
+  # Unlike when reading attributes, writing to a dead element, and
+  # other error conditions, will raise an exception.
   #
   # @example
+  #
   #   set KAXValueAttribute,        "hi"       # => "hi"
   #   set KAXSizeAttribute,         [250,250]  # => [250,250]
   #   set KAXVisibleRangeAttribute, 0..-3      # => 0..-3
   #
-  # @param [String] name an attribute constant
+  # @param [String]
   def set name, value
     code = AXUIElementSetAttributeValue(self, name, value.to_ax)
     if code.zero?
@@ -248,6 +287,9 @@ module Accessibility::Core
   # Most elements do not have parameterized attributes, but the ones
   # that do, have many.
   #
+  # Similar to {#attributes}, this method will also return an empty
+  # array if the element is dead.
+  #
   # @example
   #
   #   parameterized_attributes  # => ["AXStringForRange", ...]
@@ -266,20 +308,24 @@ module Accessibility::Core
   end
 
   ##
-  # Fetch the given pramaeterized attribute value using the given parameter.
-  # Only `AXUIElementRef` objects will be given raw, `Boxed` objects will be
-  # unwrapped for you automatically and `CFRange` objects will be turned into
-  # `Range` objects. Similarly, you do not need to worry about wrapping the
-  # parameter as that will be done for you.
+  # Fetch the given pramaeterized attribute value for the given parameter.
+  # Only `AXUIElementRef` objects will be returned in their raw form,
+  # {Boxed} objects will be unwrapped for you automatically and {CFRange}
+  # objects will be turned into {Range} objects. Similarly, you do not
+  # need to worry about wrapping the parameter as that will be done for you.
+  #
+  # As a convention, if the backing element is no longer alive, or the
+  # attribute does not exist, or a system failure occurs then you will
+  # receive `nil`.
   #
   # @example
   #
-  #   attribute KAXStringForRangeParameterizedAttribute, for_param: 1..10
+  #   parameterized_attribute KAXStringForRangeParameterizedAttribute, 1..10
   #     # => "ello, worl"
   #
-  # @param [String] attr an attribute constant
-  # @param [Object] param
-  def attribute name, for_parameter: param
+  # @param [String]
+  # @param [Object]
+  def parameterized_attribute name, param
     ptr = Pointer.new :id
     case code = AXUIElementCopyParameterizedAttributeValue(self, name, param.to_ax, ptr)
     when 0
@@ -297,8 +343,8 @@ module Accessibility::Core
 
   ##
   # Get the list of actions that the element can perform. If an element
-  # does not have actions, then an empty list will be returned.
-  # Dead elements will also return an empty array.
+  # does not have actions, then an empty list will be returned. Dead
+  # elements will also return an empty array.
   #
   # @example
   #
@@ -318,7 +364,8 @@ module Accessibility::Core
 
   ##
   # Ask an element to perform the given action. This method will always
-  # return true or raise an exception. Actions should never fail.
+  # return true or raise an exception. Actions should never fail, but
+  # there are some extreme edge cases (e.g. out of memory, etc.).
   #
   # Unlike when reading attributes, performing an action on a dead element
   # will raise an exception.
@@ -327,7 +374,7 @@ module Accessibility::Core
   #
   #   perform KAXPressAction  # => true
   #
-  # @param [String] action an action constant
+  # @param [String]
   # @return [Boolean]
   def perform action
     code = AXUIElementPerformAction(self, action)
@@ -351,7 +398,7 @@ module Accessibility::Core
   # keyup).
   #
   # You can learn more about keyboard events from the
-  # {file:docs/KeyboardEvents.markdown Keyboard Events} documentation.
+  # [Keyboard Events documentation](http://github.com/Marketcircle/AXElements/wiki/Keyboarding).
   #
   # @example
   #
@@ -365,14 +412,12 @@ module Accessibility::Core
     events.each do |event|
       code = AXUIElementPostKeyboardEvent(self, 0, *event)
       handle_error code unless code.zero?
-      sleep KEY_RATE
+      sleep @@key_rate
     end
     sleep 0.1 # in many cases, UI is not done updating right away
   end
 
   ##
-  # @todo Make this runtime configurable.
-  #
   # The delay between key presses. The default value is `0.01`, which
   # should be about 50 characters per second (down and up are separate
   # events).
@@ -382,12 +427,15 @@ module Accessibility::Core
   # were tried, but were way too big.
   #
   # @return [Number]
-  KEY_RATE = case ENV['KEY_RATE']
-             when 'VERY_SLOW' then 0.9
-             when 'SLOW'      then 0.09
-             when nil         then 0.009
-             else                  ENV['KEY_RATE'].to_f
-             end
+  def key_rate
+    @@key_rate
+  end
+  @@key_rate = case ENV['KEY_RATE']
+               when 'VERY_SLOW' then 0.9
+               when 'SLOW'      then 0.09
+               when nil         then 0.009
+               else                  ENV['KEY_RATE'].to_f
+               end
 
 
   # @group Element Hierarchy Entry Points
@@ -401,13 +449,16 @@ module Accessibility::Core
   # system (origin is in the top-left, increasing downward and to the right
   # as if reading a book in English).
   #
-  # If more than one element is at the position then the
-  # z-order of the elements will be used to determine which is
-  # "on top".
+  # If more than one element is at the position then the z-order of the
+  # elements will be used to determine which is "on top".
+  #
+  # This method will safely return `nil` if there is no UI element at the
+  # give point.
   #
   # @example
   #
   #   element_at [453, 200]  # table
+  #   element_at CGPoint.new(453, 200)  # table
   #
   # @param [#to_point]
   # @return [AXUIElementRef,nil]
@@ -426,15 +477,15 @@ module Accessibility::Core
   end
 
   ##
-  # Get the application accessibility object/token for an application
-  # given the process identifier (PID) for that application.
+  # Get the application object object/token for an application given the
+  # process identifier (PID) for that application.
   #
   # @example
   #
   #   app = application_for 54743  # => #<AXUIElementRefx00000000>
   #   CFShow(app)
   #
-  # @param [Fixnum]
+  # @param [Number]
   # @return [AXUIElementRef]
   def application_for pid
     spin_run_loop
@@ -505,17 +556,19 @@ module Accessibility::Core
 
   ##
   # @todo Should passing around a context be supported?
+  # @todo If a block is passed instead of an observer, then implicitly create
+  #       the observer.
   #
   # Register a notification observer for a specific event.
   #
   # @example
   #
-  #   register observer, to_receive: KAXWindowCreatedNotification
+  #   register observer, KAXWindowCreatedNotification
   #
   # @param [AXObserverRef]
   # @param [String]
   # @return [Boolean]
-  def register observer, to_receive: notif
+  def register observer, notif
     case code = AXObserverAddNotification(observer, self, notif, nil)
     when 0 then true
     else handle_error code, notif, observer, nil, nil
@@ -525,10 +578,14 @@ module Accessibility::Core
   ##
   # Unregister a notification that has been previously setup.
   #
+  # @example
+  #
+  #   unregister observer, KAXWindowCreatedNotification
+  #
   # @param [AXObserverRef]
   # @param [String]
   # @return [Boolean]
-  def unregister observer, from_receiving: notif
+  def unregister observer, notif
     case code = AXObserverRemoveNotification(observer, self, notif)
     when 0 then true
     else handle_error code, notif, observer, nil, nil
@@ -538,43 +595,6 @@ module Accessibility::Core
 
   # @group Misc.
 
-  ##
-  # Ask whether or not AXAPI is enabled.
-  #
-  # @example
-  #
-  #   enabled?  # => true
-  #
-  #   # After unchecking "Enable access for assistive devices" in System Prefs
-  #   enabled?  # => false
-  #
-  def enabled?
-    AXAPIEnabled()
-  end
-
-  ##
-  # Get the process identifier (PID) of the application that the element
-  # belongs to.
-  #
-  # @example
-  #
-  #   pid   # => 12345
-  #
-  # @return [Fixnum]
-  def pid
-    @pid ||= (
-      ptr = Pointer.new :int
-      case code = AXUIElementGetPid(self, ptr)
-      when 0
-        ptr.value
-      when KAXErrorInvalidUIElement
-        self == system_wide ? 0 : handle_error(code)
-      else
-        handle_error code
-      end
-      )
-  end
-
   ##
   # Create a new reference to the system wide object. This is very useful when
   # working with the system wide object as caching the system wide reference
@@ -590,7 +610,8 @@ module Accessibility::Core
   end
 
   ##
-  # Returns the application reference that the element belongs to.
+  # Returns the application reference for the application that the receiver
+  # belongs to.
   #
   # @return [AXUIElementRef]
   def application
@@ -605,7 +626,7 @@ module Accessibility::Core
   #
   #   spin_run_loop # not much to it
   #
-  # @return [self] returns the receiver
+  # @return [void]
   def spin_run_loop
     NSRunLoop.currentRunLoop.runUntilDate Time.now
   end
@@ -619,8 +640,8 @@ module Accessibility::Core
   #
   # Setting the global timeout to `0` seconds will reset the timeout value
   # to the system default. Apple does not appear to have publicly documented
-  # what the system default is though, so I can't tell you what that value
-  # is.
+  # what the system default is and there is no API to check what the value
+  # is set to, so I can't tell you what the current value is.
   #
   # @param [Number]
   # @return [Number]
@@ -647,18 +668,21 @@ module Accessibility::Core
     raise klass, msg, caller(1)
   end
 
+  # @return [String]
   def handle_failure *args
     "A system failure occurred with #{inspect}, stopping to be safe"
   end
 
+  # @todo this is a pretty crappy way of handling the various illegal
+  #       argument cases
+  # @return [String]
   def handle_illegal_argument *args
     case args.size
     when 0
       "#{inspect} is not an AXUIElementRef"
     when 1
-      "Either the element #{inspect} " +
-        "or the attribute/action/callback #{args.first.inspect} " +
-        "is not a legal argument"
+      "Either the element #{inspect} or the attribute/action/callback " +
+        "#{args.first.inspect} is not a legal argument"
     when 2
       "You can't get/set #{args.first.inspect} with/to " +
         "#{args[1].inspect} for #{inspect}"
@@ -666,70 +690,76 @@ module Accessibility::Core
       "The point #{args.first.to_point.inspect} is not a valid point, " +
         "or #{inspect} is not an AXUIElementRef"
     when 4
-      "Either the observer #{args[1].inspect}, " +
-        "the element #{inspect}, or " +
-        "the notification #{args.first.inspect} " +
-        "is not a legitimate argument"
+      "Either the observer #{args[1].inspect}, the element #{inspect}, " +
+        "or the notification #{args.first.inspect} is not a legitimate argument"
     end
   end
 
+  # @return [String]
   def handle_invalid_element *args
     "#{inspect} is no longer a valid reference"
   end
 
+  # @return [String]
   def handle_invalid_observer *args
-    "#{args[1].inspect} is no longer a valid observer for " +
-      "#{inspect} or was never valid"
+    "#{args[1].inspect} is no longer a valid observer for #{inspect} or was never valid"
   end
 
   # @param [AXUIElementRef]
+  # @return [String]
   def handle_cannot_complete *args
     spin_run_loop
     app = NSRunningApplication.runningApplicationWithProcessIdentifier pid
     if app
-      "An unspecified error occurred using #{inspect} with AXAPI" +
-        ", maybe a timeout :("
+      "An unspecified error occurred using #{inspect} with AXAPI, maybe a timeout :("
     else
       "Application for pid=#{pid} is no longer running. Maybe it crashed?"
     end
   end
 
+  # @return [String]
   def handle_attr_unsupported *args
     "#{inspect} does not have a #{args.first.inspect} attribute"
   end
 
+  # @return [String]
   def handle_action_unsupported *args
     "#{inspect} does not have a #{args.first.inspect} action"
   end
 
+  # @return [String]
   def handle_notif_unsupported *args
     "#{inspect} does not support the #{args.first.inspect} notification"
   end
 
+  # @return [String]
   def handle_not_implemented *args
     "The program that owns #{inspect} does not work with AXAPI properly"
   end
 
   # @todo Does this really neeed to raise an exception? Seems
   #       like a warning would be sufficient.
+  # @return [String]
   def handle_notif_registered *args
-    "You have already registered to hear about #{args[0].inspect} " +
-      "from #{inspect}"
+    "You have already registered to hear about #{args[0].inspect} from #{inspect}"
   end
 
+  # @return [String]
   def handle_notif_not_registered *args
-    "You have not registered to hear about #{args[0].inspect} " +
-      "from #{inspect}"
+    "You have not registered to hear about #{args[0].inspect} from #{inspect}"
   end
 
+  # @return [String]
   def handle_api_disabled *args
-    'AXAPI has been disabled'
+    "AXAPI has been disabled"
   end
 
+  # @return [String]
   def handle_param_attr_unsupported *args
     "#{inspect} does not have a #{args[0].inspect} parameterized attribute"
   end
 
+  # @return [String]
   def handle_not_enough_precision
     'AXAPI said there was not enough precision ¯\(°_o)/¯'
   end
@@ -738,24 +768,18 @@ module Accessibility::Core
 
 
   ##
-  # @private
-  #
   # `Pointer` type encoding for `CFArrayRef` objects.
   #
   # @return [String]
   ARRAY    = '^{__CFArray}'
 
   ##
-  # @private
-  #
   # `Pointer` type encoding for `AXUIElementRef` objects.
   #
   # @return [String]
   ELEMENT  = '^{__AXUIElement}'
 
   ##
-  # @private
-  #
   # `Pointer` type encoding for `AXObserverRef` objects.
   #
   # @return [String]
@@ -821,7 +845,7 @@ module Accessibility::ValueUnwrapper
   end
 end
 
-# hack to find the proper class
+# hack to find the __NSCFType class
 klass = AXUIElementCreateSystemWide().class
 klass.send :include, Accessibility::Core
 klass.send :include, Accessibility::ValueUnwrapper
@@ -838,7 +862,7 @@ class Boxed
   #
   # @return [Number]
   def self.ax_value
-    raise NotImplementedError, "#{self.class} cannot be wraped"
+    raise NotImplementedError, "#{inspect}:#{self.class} cannot be wraped"
   end
 
   ##
@@ -848,8 +872,8 @@ class Boxed
   #
   # @example
   #
-  #   CGPointMake(12, 34).to_ax # => #<AXValueRef:0x455678e2>
-  #   CGSizeMake(56, 78).to_ax  # => #<AXValueRef:0x555678e2>
+  #   CGPoint.new(12, 34).to_ax # => #<AXValueRef:0x455678e2>
+  #   CGSize.new(56, 78).to_ax  # => #<AXValueRef:0x555678e2>
   #
   # @return [AXValueRef]
   def to_ax
@@ -861,18 +885,34 @@ class Boxed
 end
 
 # AXElements extensions for `CFRange`.
-class << CFRange; def ax_value; KAXValueCFRangeType; end end
+class << CFRange
+  # (see Boxed.ax_value)
+  def ax_value; KAXValueCFRangeType end
+end
 # AXElements extensions for `CGSize`.
-class << CGSize;  def ax_value; KAXValueCGSizeType;  end end
+class << CGSize
+  # (see Boxed.ax_value)
+  def ax_value; KAXValueCGSizeType end
+end
 # AXElements extensions for `CGRect`.
-class << CGRect;  def ax_value; KAXValueCGRectType;  end end
+class << CGRect
+  # (see Boxed.ax_value)
+  def ax_value; KAXValueCGRectType end
+end
 # AXElements extensions for `CGPoint`.
-class << CGPoint; def ax_value; KAXValueCGPointType; end end
+class << CGPoint
+  # (see Boxed.ax_value)
+  def ax_value; KAXValueCGPointType end
+end
 
 
 # AXElements extensions for `NSObject`.
 class NSObject
+  ##
+  # Return an object safe for passing to AXAPI.
   def to_ax;   self end
+  ##
+  # Return a usable object from an AXAPI pointer.
   def to_ruby; self end
 end
 
@@ -914,3 +954,20 @@ class CGPoint
   # @return [CGPoint]
   def to_point; self end
 end
+
+
+##
+# AXElements extensions for `NSURL`.
+class NSString
+  ##
+  # Create an NSURL using the receiver as the initialization string.
+  # If the receiver is not a valid URL then `nil` will be returned.
+  #
+  # This exists because of
+  # [rdar://11207662](http://openradar.appspot.com/11207662).
+  #
+  # @return [NSURL,nil]
+  def to_url
+    NSURL.URLWithString self
+  end
+end