AXElements 0.6.0beta1

data/.yardopts

@@ -0,0 +1,20 @@
+--no-cache
+--no-output
+--verbose
+--markup markdown
+--markup-provider redcarpet
+--asset docs/images:images
+--readme README.markdown
+lib/**/*.rb
+ext/**/*.m
+-
+docs/Inspecting.markdown
+docs/Acting.markdown
+docs/Searching.markdown
+docs/Notifications.markdown
+docs/KeyboardEvents.markdown
+docs/Debugging.markdown
+docs/NewBehaviour.markdown
+docs/AccessibilityTips.markdown
+docs/TestingExtensions.markdown
+LICENSE.txt

data/LICENSE.txt

@@ -0,0 +1,25 @@
+Copyright (c) 2010-2011, Marketcircle Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of Marketcircle Inc. nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL Marketcircle Inc. BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.markdown

@@ -0,0 +1,150 @@
+# AXElements
+
+AXElements is a DSL abstraction built on top of the Mac OS X
+Accessibility and CGEvent APIs that allows code to be written in a
+very natural and declarative style that describes user interactions.
+
+The framework is optimized for writing tests that require automatic
+GUI manipulation, whether it be finding controls on the screen,
+typing, clicking, or other ways in which a user can interact with the
+computer.
+
+## Getting Setup
+
+You need to have the OS X developer tools installed in build and
+install AXElements (sorry). Go ahead and install the tools now if you
+haven't done that yet, I'll wait.
+
+Once, you have the developer tools, you should install MacRuby, the
+latest release should be sufficient, but nightly builds are usually
+safe as well. If you are on Snow Leopard, you will also need to
+install the
+[Bridge Support Preview](http://www.macruby.org/blog/2010/10/08/bridgesupport-preview.html).
+
+At this point you should install development dependencies. You can do
+so with `bundler` if you have it, but it will be faster to use the
+`setup_dev` task that has been provided. Simply type the following in
+terminal:
+
+    rake setup_dev
+
+__NOTE__: if you are not using RVM, then you should use `macrake`
+instead of `rake` for this command and anywhere else that you see
+`rake` in the documentation. Also, remember that if you are not using
+RVM with MacRuby but still have RVM installed then you will need to
+disable RVM like so:
+
+    rvm use system
+
+Once you are setup, you can start looking through the tutorial
+documentation to show you how to use AXElements. The first tutorial is
+the {file:docs/Inspecting.markdown Inspecting tutorial}. The full list
+of topics include:
+
+* {file:docs/Inspecting.markdown Inspecting}
+* {file:docs/Acting.markdown Acting}
+* {file:docs/Searching.markdown Searching}
+* {file:docs/Notifications.markdown Notifications}
+* {file:docs/KeyboardEvents.markdown Keyboard}
+* {file:docs/Debugging.markdown Debugging}
+* {file:docs/NewBehaviour.markdown Adding Behaviour To AXElements}
+* {file:docs/AccessibilityTips.markdown Making Your Apps More Accessibile}
+* {file:docs/TestingExtensions.markdown Test Suite Extensions for RSpec, Minitest, etc.}
+
+## Documentation
+
+AXElements is documented using YARD, and includes a few tutorials in
+the `docs/` directory. If you do not want to generate the
+documentation yourself then you can go to
+[rdoc.info](http://rdoc.info/gems/AXElements/frames).
+
+Though it is not required, you may want to read Apple's
+[Accessibility Overview](http://developer.apple.com/library/mac/#documentation/Accessibility/Conceptual/AccessibilityMacOSX/OSXAXModel/OSXAXmodel.html)
+as a primer on some the technical underpinnings of AXElements.
+
+## Test Suite
+
+Before starting development on your machine, you should run the test
+suite and make sure things are kosher. The nature of this library
+requires that the tests take over your computer while they run. The
+tests aren't programmed to do anything destructive, but if you
+interfere with them then something could go wrong.
+
+To run the tests you simply need to run the `test` task:
+
+    rake test
+
+__NOTE__: there may be some tests are dependent on Accessibility
+features that are new in OS X Lion which will cause test failures on
+OS X Snow Leopard. If you have any issues then you should look at the
+output to find hints at what went wrong and/or log a bug. I will still
+support Snow Leopard as long as MacRuby does, but I do not have easy
+access to a Snow Leopard machine to verify that things still work.
+
+### Benchmarks
+
+Benchmarks are also included as part of the test suite, but they are
+disabled by default. In order to enable them you need to set the
+`BENCH` environment variable:
+
+    BENCH=1 rake test
+
+Benchmarks only exist for code that is known to be slow. I'm keeping
+tabs on slow code so that I be confident about getting depressed when
+it gets slower. Though, there is still room for improved performance
+as well.
+
+## Road Map
+
+There are still a bunch of things that could be done to improve
+AXElements. The README only contains an idealized outline of some of
+the high-level items that should get done in the next couple of
+releases. Smaller items are peppered through the code base and marked
+with `@todo` tags.
+
+### 0.7 (or maybe 1.0)
+
+- Pre-loading AX hierarchy and attribute cache from
+  `/System/Library/Accessibility/AccessibilityDefinitions.plist`
+  + Not available on Snow Leopard, so it will have to wait anyways
+  + Probably inccurs too much overhead at boot time right now
+- Make a decision about NSArray#method_missing
+- Merge notifications with actions as they are commonly combined
+  + But how?
+- Rewrite core module to handle errors more gracefully
+- Mouse module cleanup and regression testing
+- Test suite deduplication cleanup and better isolation
+- Performance tweaks
+- The OO abstraction leaks in a few places, code needs to be
+  refactored without hurting performance too much
+- Test framework helpers
+  + Minitest
+  + RSpec
+- Thread Safety
+  + Only if it becomes an issue, otherwise it might be better to
+  forget thread safey to simplify and optimize existing code
+
+### Future
+
+- Screenshot taking and diff'ing abilities for those rare cases when
+  you need it
+- Address Book helpers, and other friends
+
+## Contributing to AXElements
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2010-2011 Marketcircle Incorporated. All rights
+reserved.
+
+AXElements is available under the standard 3-clause BSD license. See
+{file:LICENSE.txt LICENSE.txt} for further details.
+

data/Rakefile

@@ -0,0 +1,109 @@
+require 'rubygems'
+
+task :default => :gem
+task :clean   => :clobber
+
+def safe_require path, name
+  require path
+  yield
+rescue LoadError => e
+  $stderr.puts "It seems as though you do not have #{name} installed."
+  command = ENV['RUBY_VERSION'] ? 'gem' : 'sudo macgem'
+  $stderr.puts "You can install it by running `#{command} install #{name}`."
+end
+
+
+## Documentation
+
+safe_require 'yard', 'yard' do
+  YARD::Rake::YardocTask.new
+end
+
+desc 'Generate Graphviz object graph'
+task :garden => :yard do
+  sh 'yard graph --full --dependencies --dot="-Tpng:quartz" -f docs/images/AX.dot'
+end
+
+## Console
+
+desc 'Start up irb with AXElements loaded'
+task :console => :ext do
+  irb = ENV['RUBY_VERSION'] ? 'irb' : 'macirb'
+  sh "#{irb} -Ilib -Iext/key_coder -rubygems -rax_elements"
+end
+
+## Compilation
+
+require 'rake/compiletask'
+Rake::CompileTask.new
+
+desc 'Compile C extensions'
+task :ext do
+  Dir.chdir 'ext/key_coder' do
+    break if File.exists?('key_coder.bundle') && File.mtime('key_coder.bundle') > File.mtime('key_coder.m')
+    ruby 'extconf.rb'
+    sh   'make'
+  end
+end
+
+desc 'Clean temporary files created by the C extension'
+task :clobber_ext do
+  Dir.chdir 'ext/key_coder' do
+    ['Makefile', 'key_coder.o', 'key_coder.bundle'].each do |file|
+      $stdout.puts "rm ext/key_coder/#{file}"
+      rm file
+    end
+  end
+end
+task :clobber => :clobber_ext
+
+## Testing
+
+desc 'Open the fixture app'
+task :run_fixture => :fixture do
+  sh 'open test/fixture/Release/AXElementsTester.app'
+end
+
+desc 'Build the test fixture'
+task :fixture do
+  sh 'cd test/AXElementsTester && xcodebuild'
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.libs     << 'test' << 'ext/key_coder'
+  t.pattern   = 'test/**/test_*.rb'
+  t.ruby_opts = ['-rhelper']
+  t.verbose   = true
+end
+task :test => [:ext, :fixture]
+
+## Gem Packaging
+require 'rubygems/dependency_installer'
+require 'rake/gempackagetask'
+
+spec = Gem::Specification.load('AXElements.gemspec')
+
+Rake::GemPackageTask.new(spec) { }
+
+# This only installs this gem, it does not take deps into consideration
+desc 'Build gem and install it'
+task :install => :gem do
+  Gem::Installer.new("pkg/#{spec.file_name}").install
+end
+
+desc 'Install dependencies for a test node'
+task :setup_node do
+  spec.runtime_dependencies.each do |dep|
+    puts "Installing #{dep.name}"
+    Gem::DependencyInstaller.new.install(dep.name, dep.requirement)
+  end
+end
+
+desc 'Install dependencies for development'
+task :setup_dev => :setup_node do
+  spec.development_dependencies.each do |dep|
+    puts "Installing #{dep.name}"
+    Gem::DependencyInstaller.new.install(dep.name, dep.requirement)
+  end
+end

data/docs/AccessibilityTips.markdown

@@ -0,0 +1,119 @@
+# Accessibility Tips
+
+This document includes tips for customizing accessibility in your own
+applications. The goal is to inform you of pitfalls that are not
+mentioned in Apple's documentation. It also includes notes on how to
+avoid making decsions that will make an application incompatible with
+AXElements.
+
+@todo This document is under construction and is currently just a set
+of notes and unorganized sections ripped from other documents.
+
+## Guidelines
+
+When implementing custom accessibility roles, you should never use a
+pluralized name for the role. A role that is already pluralized will
+break search.
+
+
+## Adding new stuff
+
+Adding new attributes to an object is very simple...usually. Most of
+the time it is as simple as overriding two methods:
+
+- `accessibilityAttributeNames`
+- `accessibilityAttributeValue:`
+
+`accessibilityAttributeNames` needs to return an array with the names
+of available attributes. You should call `super` to get the existing
+array first, and then append any custom attributes you want to
+provide.
+
+An attribute name must follow the convention of being a camel cased
+string with the "AX" prefix, such as `AXTitle`. You can optionally
+include an additional prefix before "AX", such as "MCAX" for
+Marketcircle custom attributes. If you do not follow these rules then
+attribute names will not be translated properly by AXElements.
+
+`accessibilityAttributeValue:` is how you actually provide the value
+for the attribute; the parameter for this method is the name of the
+attribute fetched from calling `accessibilityAttributeNames`. You
+should return the value without doing any extra work to the data; the
+Accessibility interface will do any wrapping or translating for
+you (e.g. CGPoint objects will have co-ordinates flipped). In the case
+of a C structs you should leave them wrapped in an NSValue object.
+
+Similarly, parameterized attributes are added using methods with
+`Parameter` in the name. The method for getting the value of a
+parameterized attribute will of course take an extra parameter for the
+parameterized attributes parameter.
+
+### Where To Implement The Methods
+
+The difficulty in adding attributes lies in finding out where you need
+to add the accessibility methods. Often, the class that implements
+accessibility is the class that draws the user interface element. For
+example, the accessibility information for a button is implemented on
+the button cell and not the button itself. Since Apple is under the
+delusion that you will never need to add any custom accessibility
+information, they really don't document these customizations enough,
+and so this document only includes caveats that have been discovered
+so far.
+
+It is often inconvenient to subclass the cell for an object just for
+accessibility. In these cases Apple has provided something similar to
+singleton methods, but less useful, with the
+`accessibilitySetOverrideValue:forAttribute:` method. You can use the
+method to override an attribute or even add a new one. The main issue
+with this method is that any attribute that is overridden, or added,
+will not be writable using the accessibility APIs. Another issue is
+that you have to calculate the value when you override instead of when
+the attribute value is queried by the client.
+
+### Writability
+
+In the case where it is convenient to be able to change an attribute's
+value through accessibility, like the size of a window, you will also
+need to implement two more methods for the attribute:
+
+- `accessibilityIsAttributeSettable:`
+- `accessibilitySetValue:forAttribute:`
+
+`accessibilityIsAttributeSettable:` simply responds with whether or
+not the attribute is writable, and
+`accessibilitySetValue:forAttribute:` will be called to actually write
+to the attribute.
+
+### Remember `super`
+
+It is important to remember that these methods are already implemented
+for the built in features. When overriding, you should only implement
+the custom behaviour and call `super` to handle everything else.
+
+### Existing Definitions
+
+When implementing custom behaviour, you should try and use
+pseudoclasses that have already been defined by Apple, as well as
+attributes, parameterized attributes, and other features that have
+already been defined. Apple maintains the documentation for all their
+definitions on
+[here](http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Introduction.html#//apple_ref/doc/uid/TP40007870).
+The documentation is fairly detailed now (moreso than before), but
+still misses a few things.
+
+
+## Adding Accessibility Actions
+
+If you have access to the source code for an app, you can add more
+accessibility actions. You need to override two methods, just like
+with adding attributes:
+
+– `accessibilityActionNames`
+– `accessibilityPerformAction:`
+
+These methods should be implemented in the same way that you would
+implement new attributes, just as detailed in the
+{file:docs/Inspecting.markdown Inspecting tutorial}. The one
+difference is that `accessibilityPerformAction:` should not return
+anything after it performs the action.
+