AXElements 0.7.8 → 0.8.0

data/lib/ax/element.rb

@@ -1,18 +1,22 @@
 # -*- coding: utf-8 -*-
 
-require 'ax_elements/vendor/inflector'
+require 'accessibility/core'
+require 'accessibility/factory'
+require 'accessibility/translator'
 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.
+# The abstract base class for all accessibility objects. `AX::Element`
+# 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
@@ -39,10 +43,11 @@ class AX::Element
   end
 
   ##
-  # @todo Consider returning `nil` if the element does not have
-  #       the given attribute.
-  #
-  # Get the value of an attribute.
+  # 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.
   #
   # @example
   #
@@ -54,9 +59,12 @@ class AX::Element
   end
 
   ##
-  # Needed to override inherited `NSObject#description` as some
-  # elements have a `description` attribute. If you want a description
-  # of the object then you should use {#inspect} instead.
+  # Get the accessibility description for the element.
+  #
+  # This overrides the inherited `NSObject#description`. If you want a
+  # description of the object then you should use {#inspect} instead.
+  #
+  # @return [String]
   def description
     attribute :description
   end
@@ -71,20 +79,24 @@ class AX::Element
   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.
+  # Get a list of elements, starting with the receiver and riding
+  # the hierarchy up to the top level object (i.e. the {AX::Application}).
   #
   # @example
   #
-  #   table.size_of  :rows     # => 111
-  #   window.size_of :children # => 16
+  #   element = AX::DOCK.list.application_dock_item
+  #   element.ancestry
+  #     # => [#<AX::ApplicationDockItem...>, #<AX::List...>, #<AX::Application...>]
   #
-  # @param [#to_sym]
-  # @return [Number]
-  def size_of attr
-    @ref.size_of TRANSLATOR.cocoaify attr
+  # @return [Array<AX::Element>]
+  def ancestry *elements
+    elements = [self] if elements.empty?
+    element  = elements.last
+    if element.attributes.include? :parent
+      ancestry(elements << element.parent)
+    else
+      elements
+    end
   end
 
   ##
@@ -100,6 +112,23 @@ class AX::Element
     @ref.pid
   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
+    @ref.size_of TRANSLATOR.cocoaify attr
+  end
+
   ##
   # Check whether or not an attribute is writable.
   #
@@ -125,7 +154,7 @@ class AX::Element
   # @return the value that you were setting is returned
   def set attr, value
     unless writable? attr
-      raise NoMethodError, "#{attr} is read-only for #{inspect}"
+      raise ArgumentError, "#{attr} is read-only for #{inspect}"
     end
     value = value.relative_to(@ref.value.size) if value.kind_of? Range
     @ref.set TRANSLATOR.cocoaify(attr), value
@@ -153,14 +182,12 @@ class AX::Element
   #
   # @example
   #
-  #  text_field.attribute :string_for_range, for_param: (2..8).relative_to(10)
+  #  text_field.parameterized_attribute :string_for_range, 2..8
   #
   # @param [#to_sym]
-  def attribute attr, for_parameter: param
-    if rattr = TRANSLATOR.cocoaify(attr)
-      param = param.relative_to(@ref.value.size) if value.kind_of? Range
-      process @ref.attribute(rattr, for_parameter: param)
-    end
+  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)
   end
 
 
@@ -196,11 +223,7 @@ class AX::Element
   # @param [#to_sym]
   # @return [Boolean] true if successful
   def perform action
-    if raction = TRANSLATOR.cocoaify(action)
-      @ref.perform raction
-    else
-      false
-    end
+    @ref.perform TRANSLATOR.cocoaify action
   end
 
 
@@ -208,14 +231,15 @@ class AX::Element
 
   ##
   # Perform a breadth first search through the view hierarchy rooted at
-  # the current 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 {file:docs/Searching.markdown Searching} tutorial for the
-  # details on searching.
+  # See the [Searching Tutorial](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' )
+  #   AX::DOCK.search(:application_dock_item, title:'Finder')
   #
   # @param [#to_s]
   # @param [Hash{Symbol=>Object}]
@@ -233,7 +257,7 @@ class AX::Element
   end
 
   ##
-  # Search for an ancestor of the current elemenet.
+  # Search for an ancestor of the current element.
   #
   # As the opposite of {#search}, this also takes filters, and can
   # be used to find a specific ancestor for the current element.
@@ -261,22 +285,30 @@ class AX::Element
   # lookup is always tried first, followed by a parameterized attribute
   # lookup, and then finally a search.
   #
-  # Failing all lookups, this method calls `super`.
+  # Failing all lookups, this method calls `super`, which will probably
+  # raise an exception; however, most elements have children and so it
+  # is more likely that you will get an {Accessibility::SearchFailure}
+  # in cases where you sholud get a `NoMethodError`.
   #
   # @example
   #
-  #   mail   = AX::Application.application_with_bundle_identifier 'com.apple.mail'
+  #   mail   = Accessibility.application_with_bundle_identifier 'com.apple.mail'
   #
   #   # attribute lookup
   #   window = mail.focused_window
   #   # is equivalent to
   #   window = mail.attribute :focused_window
   #
+  #   # attribute setting
+  #   window.position = CGPoint.new(100, 100)
+  #   # is equivalent to
+  #   window.set :position, CGPoint.new(100, 100)
+  #
   #   # parameterized attribute lookup
-  #   window.title_ui_element.string_for_range (1..10).relative_to(100)
+  #   window.title_ui_element.string_for_range 1..10
   #   # is equivalent to
   #   title = window.attribute :title_ui_element
-  #   title.param_attribute :string_for_range, for_param: (1..10).relative_to(100)
+  #   title.parameterized_attribute :string_for_range, 1..10
   #
   #   # simple single element search
   #   window.button # => You want the first Button that is found
@@ -293,7 +325,7 @@ class AX::Element
   #   # is equivalent to
   #   window.search :button, title: 'Log In'
   #
-  #   # attribute and element search failure
+  #   # searching from #method_missing will #raise if nothing is found
   #   window.application # => SearchFailure is raised
   #
   def method_missing method, *args, &block
@@ -301,10 +333,10 @@ class AX::Element
 
     key = TRANSLATOR.cocoaify method
     if @ref.attributes.include? key
-      return attribute method
+      return attribute(method)
 
     elsif @ref.parameterized_attributes.include? key
-      return attribute(method, for_parameter: args.first)
+      return paramaterized_attribute(method, args.first)
 
     elsif @ref.attributes.include? KAXChildrenAttribute
       if (result = search(method, *args, &block)).blank?
@@ -319,78 +351,11 @@ class AX::Element
     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 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.
+  # Get relevant details about the current object.
   #
   # @return [String]
   def inspect
@@ -413,6 +378,25 @@ class AX::Element
     inspect
   end
 
+  ##
+  # Get the relevant details about the receiver and also the children
+  # and further descendents of the receiver. Each generation down the
+  # tree will be indented one level further.
+  #
+  # @example
+  #
+  #   puts app.inspect_subtree
+  #
+  # @return [String]
+  def inspect_subtree
+    output = self.inspect + "\n"
+    enum   = Accessibility::Enumerators::DepthFirst.new self
+    enum.each_with_level do |element, depth|
+      output << "\t"*depth + element.inspect + "\n"
+    end
+    output
+  end
+
   ##
   # Overriden to respond properly with regards to dynamic attribute
   # lookups, but will return false for potential implicit searches.
@@ -430,22 +414,22 @@ class AX::Element
   #
   # @return [CGPoint]
   def to_point
-    size     = attribute :size
-    point    = attribute :position
+    size  = attribute :size
+    point = attribute :position
     point.x += size.width  / 2
     point.y += size.height / 2
     point
   end
+  alias_method :hitpoint, :to_point
 
   ##
   # Get the bounding rectangle for the element.
   #
   # @return [CGRect]
   def bounds
-    point = attribute :position
-    size  = attribute :size
-    CGRectMake(*point, *size)
+    CGRect.new(attribute(:position), attribute(:size))
   end
+  alias_method :rect, :bounds
 
   ##
   # Get the application object for the element.
@@ -455,24 +439,31 @@ class AX::Element
     process @ref.application
   end
 
-  ##
-  # Concept borrowed from `Active Support`. It is used during implicit
-  # searches to determine if searches yielded responses.
+  # (see NilClass#blank?)
   def blank?
     false
   end
 
   ##
-  # @todo Need to add '?' to predicate methods, but how?
+  # 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.
+  def invalid?
+    @ref.role.nil?
+  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)
   end
 
   ##
-  # Overridden so that equality testing would work. A hack, but the only
-  # sane way I can think of to test for equivalency.
+  # 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
@@ -482,36 +473,29 @@ class AX::Element
 
   private
 
-  ##
   # @private
-  #
-  # Performance hack.
-  #
   # @return [String]
   EQUALS = '='
 
-  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
+end
+
 
+# Extensions so checking `#blank?` on search result "just works".
+class NSArray
+  # (see NilClass#blank?)
+  alias_method :blank?, :empty?
+end
+
+# Extensions so checking `#blank?` on search result "just works".
+class NilClass
   ##
-  # @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.
+  # 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?`.
   #
-  def _unregister_notification observer, notif, source
-    CFRunLoopRemoveSource(CFRunLoopGetCurrent(), source, KCFRunLoopDefaultMode)
-    @ref.unregister observer, from_receiving: notif
+  # This method is used by implicit searching in AXElements to
+  # determine if searches yielded responses.
+  def blank?
+    true
   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/pop_up_button.rb

@@ -0,0 +1,12 @@
+require 'ax/element'
+
+##
+# UI Element for pop up buttons.
+class AX::PopUpButton < AX::Element
+end
+
+##
+# An alias for {AX::PopUpButton}.
+#
+# @return [Class]
+AX::PopUp = AX::PopUpButton

data/lib/ax/radio_button.rb

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

data/lib/ax/row.rb

@@ -2,13 +2,13 @@ require 'ax/element'
 require 'accessibility/qualifier'
 
 ##
-# UI Element for the row in a table, outline, etc.
+# UI Element for the row in a table, outline view, 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.
+  # search or wait.
   #
   # 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.

data/lib/ax/static_text.rb

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

data/lib/ax/systemwide.rb

@@ -23,25 +23,37 @@ class AX::SystemWide < AX::Element
   #
   # Generate keyboard events by simulating keyboard input.
   #
-  # See the {file:docs/KeyboardEvents.markdown Keyboard} documentation for
-  # more information on how to format strings.
+  # See the
+  # [Keyboarding documentation](http://github.com/Marketcircle/AXElements/wiki/Keyboarding)
+  # for more information on how to format strings.
   #
   # @return [Boolean]
   def type string
     @ref.post keyboard_events_for string
     true
   end
+  alias_method :type_string, :type
 
-  # @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
+  ##
+  # 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 # if block raises the button might stuck, so ensure it is released
+    @ref.post [[code,false]] if code
+    code
   end
 
   ##

data/lib/ax_elements/awesome_print.rb

@@ -1,12 +1,21 @@
 require 'awesome_print'
 
+##
+# `AwesomePrint` extension for AXElements.
 module AwesomePrint::AXElements
 
+  ##
+  # Perform the silly `alias_method_chain` stuff that AwesomePrint
+  # expects.
   def self.included base
     base.send :alias_method, :cast_without_ax_elements, :cast
     base.send :alias_method, :cast, :cast_with_ax_elements
   end
 
+  ##
+  # Format {AX::Element} objects for AwesomePrint. For the time
+  # being, just work-around the default AwesomePrint output by
+  # using the default `#inpspect` for {AX::Element}.
   def cast_with_ax_elements object, type
     cast = cast_without_ax_elements object, type
     cast = :ax_element if object.kind_of? ::AX::Element
@@ -16,6 +25,10 @@ module AwesomePrint::AXElements
 
   private
 
+  ##
+  # Give the awesome output for an {AX::Element} object.
+  #
+  # @return [String]
   def awesome_ax_element object
     object.inspect
   end

data/lib/ax_elements/exception_workaround.rb

@@ -2,6 +2,11 @@
 # Workaround for MacRuby ticket #1334
 class Exception
   alias_method :original_message, :message
+  #
+  # Override the message method to force the backtrace to be
+  # included.
+  #
+  # @return [String]
   def message
     "#{original_message}\n\t#{backtrace.join("\n\t")}"
   end

data/lib/ax_elements/nsarray_compat.rb

@@ -53,6 +53,7 @@ module Accessibility::NSArrayCompat
   private
 
   # @private
+  # @return [Accessibility::Translator]
   TRANSLATOR = Accessibility::Translator.instance
 
 end

data/lib/ax_elements.rb

@@ -6,13 +6,14 @@ include Accessibility::DSL
 # The Mac OS X dock application.
 #
 # @return [AX::Application]
-AX::DOCK = app_with_bundle_identifier 'com.apple.dock'
+AX::DOCK = AX::Application.new('com.apple.dock')
 
 # Load explicitly defined elements that are optional
 require 'ax/button'
 require 'ax/radio_button'
 require 'ax/row'
 require 'ax/static_text'
+require 'ax/pop_up_button'
 
 # Misc things that we need to load
 require 'ax_elements/nsarray_compat'