AXElements 0.6.0beta2 → 0.7.5

data/.yardopts

@@ -6,7 +6,7 @@
 --asset docs/images:images
 --readme README.markdown
 lib/**/*.rb
-ext/**/*.m
+ext/**/*{.m,.c}
 -
 docs/Inspecting.markdown
 docs/Acting.markdown
@@ -17,4 +17,3 @@ docs/Debugging.markdown
 docs/NewBehaviour.markdown
 docs/AccessibilityTips.markdown
 docs/TestingExtensions.markdown
-LICENSE.txt

data/README.markdown

@@ -9,58 +9,141 @@ GUI manipulation, whether it be finding controls on the screen,
 typing, clicking, or other ways in which a user can interact with the
 computer.
 
+
+## Demo
+
+Perhaps you want to do something with the finder. This example opens a
+new Finder window, finds Activity Monitor, and then opens the application
+from a quick look window:
+
+```ruby
+    require 'rubygems'
+    require 'ax_elements'
+
+    finder = app_with_bundle_identifier 'com.apple.finder'
+    set_focus finder # bring to the front so you can see it happening
+
+    type "\\COMMAND+n"
+    sleep 1 # this is so you can see it happen in "slow motion"
+
+    window = finder.main_window
+    click window.outline.row(static_text: { value: 'Applications' })
+
+    utilities = window.row(text_field: { filename: 'Utilities' })
+    scroll_to utilities
+    double_click utilities
+
+    activity_monitor = window.text_field( filename: /Activity Monitor/ )
+    scroll_to activity_monitor
+    click activity_monitor
+    type " " # type a space, which should bring up quick look
+    sleep 1
+
+    click finder.quick_look.button(id: 'QLControlOpen')
+```
+
+A simpler example would be changing the system volume by moving the
+slider in the menu bar (unless you've hidden it):
+
+```ruby
+    require 'rubygems'
+    require 'ax_elements'
+
+    ui     = app_with_bundle_id 'com.apple.systemuiserver'
+    volume = ui.menu_extra(description: 'system sound volume')
+
+    click volume
+    15.times { decrement volume.slider }
+    15.times { increment volume.slider }
+```
+
+
 ## 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
+haven't done that yet, I'll wait. Once you have the developer tools,
+you should install MacRuby, the latest nightly build is required. 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:
+Then you can install AXElements. You can install AXElements via
+rubygems:
+
+```bash
+    gem install AXElements
+```
+
+Or you can install from source:
 
-    rake setup_dev
+```bash
+    cd ~/Documents # or where you want to put the AXElements code
+    git clone git://github.com/Marketcircle/AXElements
+    cd AXElements
+    rake install
+```
 
-__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:
+AXElements has no gem dependencies, so you can try it out in `macirb` at
+this point:
 
+```bash
+    rake console
+```
+
+__NOTE__: If you are not using RVM, then you should use `macrake`
+instead of `rake`, and do so for any other references to `rake` in the
+documentation. You may also need to add `sudo` to your command when you
+install the gem. 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:
+
+```bash
     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.}
+## Getting Started
 
-## Documentation
+The
+[documentation](http://rdoc.info/github/Marketcircle/AXElements/master/frames)
+is the best place to get started, it includes tutorials to help you get
+started as well the API documentation (API docs are broken right now due
+to incompatabilities between MacRuby and YARD). The starting tutorial is the
+[Inspecting Tutorial](docs/Inspecting.markdown).
 
-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).
+Documentation is hosted by rdoc.info, but you can also generate it yourself
+using YARD. Documentation is stored in the `docs/` directory, but the
+documentation includes a number of cross references and even some
+pictures so you will lose a lot of the quality if you view them as
+plain text.
 
 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.
+as a primer on some the rationale for the accessibility APIs as well
+as the technical underpinnings of AXElements.
+
+
+## Development
+
+Development of a stable release of AXElements is under way! The main
+focus is an overall refactoring to create a more robust core, end user
+features will become more consistent, and performance will
+increase. Documentation will be overhauled and more examples will be
+added. It will be magical, so we're code naming the next version
+"Clefairy".
+
+![The Moon](https://github.com/Marketcircle/AXElements/raw/master/docs/images/next_version.png)
+
+Proper releases to rubygems will be made as milestones are reached.
+
+### Road Map
+
+There are still a bunch of things that could be done to improve
+AXElements. Some of the higher level tasks are outlined in various
+[Github Issues](http://github.com/Marketcircle/AXElements/issues).
+Smaller items are peppered through the code base and marked with `@todo`
+tags.
+
 
 ## Test Suite
 
@@ -68,18 +151,18 @@ 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:
+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
+__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.
+output to find hints at what went wrong and/or log a bug. AXElements
+will support Snow Leopard for as long as MacRuby does, but I do not
+have easy access to a Snow Leopard machine to verify that things still
+work.
 
 ### Benchmarks
 
@@ -89,46 +172,6 @@ disabled by default. In order to enable them you need to set the
 
     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
 
@@ -140,11 +183,32 @@ with `@todo` tags.
 * 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.
+## Copyright
 
+Copyright (c) 2010-2012, 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/Rakefile

@@ -1,109 +1,14 @@
 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
+task :default => :test
 
-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
+desc 'Remove all generated files'
+task :clean   => :clobber
+desc 'Remove all generated files'
 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 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 'Compile C extensions'
+task :ext => 'ext:key_coder'
 
-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
+desc 'Run all tests'
+task :test => ['test:sanity', 'test:integration', 'test:cruby']

data/docs/Debugging.markdown

@@ -69,6 +69,13 @@ want to have turned into a dot graph; you will get a string back that
 you will then need to give to Graphviz in order to generate the visual
 graph.
 
+    File.open('graph.dot', 'w') do |file|
+      app = Accessibility.application_with_name 'Terminal'
+      file.write Accessibility.graph(app.window)
+    end
+    `dot graph.dot -Tpng > graph.png`
+    `open graph.png`
+
 ### Text Tree Won't Print?
 
 AXElements isn't perfect and it is possible that an edge case slipped
@@ -81,8 +88,8 @@ AXElements was that you could not search through the menu bar causing
 a text dump to fail in a very difficult to trace manner.
 
 In these cases you will need to use your deductive reasoning to figure
-out where the problem is coming from. Fortunately, AXElements has some
-tools to help you along the way.
+out where the problem is coming from. Fortunately, I have provided
+some tools to help you along the way.
 
 ## All The Way Up
 

data/docs/KeyboardEvents.markdown

@@ -1,57 +1,122 @@
 # Keyboard Events
 
-@todo Still a little bit to do in this doc
+Keyboard events are a system provided by Apple that allows you to
+simulate keyboard input. The API for this in the `ApplicationServices`
+framework, but there is an analogue in the `Acessibility` APIs which
+has the additional option of directing the input to a specific application.
 
-In some cases you cannot, or do not want to,  set the value of a field
-directly by assigning to the accessibility object's value
-attribute. In these cases you can post keyboard events to an
-application object.
+Using accessibility actions and setting attributes you can already
+perform most of the interactions that would be possible with the
+keyboard simulation. However, there are some things that you will need
+to, or it will just make more sense to, simulate keyboard input. For
+example, to make use of hot keys you would have to add extra actions
+or attributes to a control in the application; that would be more
+work, possibly prone to error, than simply simulating the hot key from
+outside the application. In other situations you may specifically want
+to test out keyboard navigation and so actions would not be a good
+substitute. It may be that the APIs that AXElements provides for
+typing just make more sense when writing tests or scripts.
 
-Other cases for using keyboard input simulation might include keyboard
-navigation or hotkey activation.
+## Typing with the DSL
 
-The DSL exposes Keyboard events through the `type` keyword. An example
-would look like this:
+The {Accessibility::DSL} mix-in exposes keyboard events through the
+`type` method. A simple example would look like this:
 
-```ruby
-type "hello, world!", app
-```
+    type "Hello, #{ENV['USER']}! How are you today?\n"
+
+And watch your computer come to life! The `type` command takes an
+additional optional parameter that we'll get to later. The first
+parameter is just a string that you want AXElements to type out. How
+to format the string should be obvious for the most part, but some
+things like the command key and arrows might not be so obvious.
+
+## Formatting Strings
+
+Letters and numbers should be written just as you would for any other
+string. Any of the standard symbols can also be plainly added to a
+string that you want to have typed. Here are some examples:
+
+    type "UPPER CASE LETTERS"
+    type "lower case letters"
+    type "1337 message @/\/|) 57|_||=|="
+    type "A proper sentence can be typed out (all at once)."
+
+### Regular Escape Sequences
+
+Things like newlines and tabs should be formatted just like they would
+ in a regular string. That is, normal string escape sequences should
+ "just work" with AXElements. Here are some more examples:
+
+    type "Have a bad \b\b\b\b\b good day!"
+    type "First line.\nSecond line."
+    type "I \t like \t to \t use \t tabs \t a \t lot."
+    type "Explicit\sSpaces."
+
+### Custom Escape Sequences
+
+Unfortunately, there is no built in escape sequence for deleting to
+the right or pressing command keys like `F1`. AXElements defines some
+extra escape sequences in order to easily represent the remaining
+keys.
+
+These custom escape sequences __shoud start with two `\` characters__,
+as in this example:
+
+    type "\\F1"
+
+A custom escape sequence __should terminate with a space or the end of
+the string__, as in this example:
+
+    type "\\PAGEDOWN notice the space afterwards\\PAGEUP but not before"
+
+The full list of supported custom escape sequences is listed in
+{Accessibility::StringParser::CUSTOM}. Some escapes have an alias,
+such as the right arrow key which can be escaped as `"\\RIGHT"` or as
+`"\\->"`.
+
+### Hot Keys
+
+To support pressing multiple keys at the same time (i.e. hot keys), you
+must start with the custom escape sequence for the combination and
+instead of ending with a space you should put a `+` character to chain
+the next key. The entire sequence should be ended with a space or
+nil. Some common examples are opening a file or quitting an
+application:
+
+    type "\\COMMAND+o"
+    type "\\CONTROL+a Typing at the start of the line"
+    type "\\COMMAND+\\SHIFT+s"
+
+You might also note that `CMD+SHIFT+s` could also be:
+
+    type "\\COMMAND+S"
+
+Since a capital `S` will cause the shift key to be held down.
+
+One caveat with hot keys is that you cannot use `"\\COMMAND+ "` to
+represent command and space combination, you will need to use
+`"\\COMMAND+\s"` instead.
+
+## Protips
 
 In order make sure that certain sequences of characters are properly
-transcribed to the screen you should be consistent about using double
-quotes, `"`,  for literal strings. An escape sequence should begin
-`\\`.
-
-First the keyword `type`, and then the string you want to type
-out. Finally, there is a second argument, which is optional, that
-should be the application that you wish to send the keyboard input
-to; if you do not include the argument, then the input will go to the
-currently activate application.
-
-## Behaviour
-
-The method is asynchronous. It appears to type information in at the
-keyboard repeat rate, but I have yet to check that out.
-
-## Escape Sequences
-
-A number of custom escape sequences have been added in order to allow easy
-encoding of all key sequences/combinations.
-
-<table style="1px solid black">
-<tr><td>Key</td><td>Escape Sequence</td></tr>
-<tr><td>Delete Backwards (Backspace)</td><td>`\b`</td></tr>
-<tr><td>Enter</td><td>`\n` or `\r`</td></tr>
-<tr><td>Control</td><td>`\^`</td></tr>
-<tr><td>Command</td><td>`\C`</td></tr>
-<tr><td>Option/Alt</td><td>`\O`</td></tr>
-<tr><td>Tab</td><td>`\t`</td></tr>
-<tr><td>Escape</td><td>`\e`</td></tr>
-<tr><td>Space</td><td>` `</td></tr>
-<tr><td>Scroll To Top</td><td>`\x01`</td></tr>
-<tr><td>Scroll To Bottom</td><td>`\x04`</td></tr>
-<tr><td>Page Down</td><td>`\f`</td></tr>
-<tr><td>Left Arrow</td><td>`\\<->`</td></tr>
-<tr><td>Right Arrow</td><td>`\\->`</td></tr>
-<tr><td>Down Arrow</td><td>`\DOWN`</td></tr>
-</table>
+escaped, it is recommended to simply always use double quoted
+strings.
+
+### Posting To A Specific Application
+
+The second argument to the `type` command can be an {AX::Application}
+object. If you do not include the argument, the events will be posted
+to the system, which usually means the application that currently is
+active. Note that you cannot be more specific than the application
+that you want to send the events to, within the application, the
+control that has keyboard focus will receive the events.
+
+### Changing Typing Speed
+
+You can set the typing speed at load time by setting the environment
+variable `KEY_RATE`. See {Accessibility::Core::KEY\_RATE} for details on
+possible values. An example of using it would be:
+
+    KEY_RATE=SLOW irb -rubygems -rax_elements
+    KEY_RATE=0.25 rspec gui_spec.rb

data/docs/Setting.markdown

@@ -0,0 +1 @@
+You can use ruby ranges, but there is one caveat, which is that negative ranges will have to be converted ahead of time by the programmer, but only if you are using Core directly. If you are using an AX::Element derived class then it will Just Work™.

data/ext/accessibility/key_coder/extconf.rb

@@ -0,0 +1,22 @@
+require 'mkmf'
+
+$CFLAGS << ' -std=c99 -Wall -Werror -ObjC'
+$LIBS   << ' -framework Cocoa -framework Carbon -framework ApplicationServices'
+
+if RUBY_ENGINE == 'macruby'
+  $CFLAGS << ' -fobjc-gc'
+else
+  unless RbConfig::CONFIG["CC"].match /clang/
+    clang = `which clang`.chomp
+    if clang.empty?
+      $stdout.puts "Clang not installed. Cannot build C extension"
+      exit 1
+    else
+      RbConfig::MAKEFILE_CONFIG["CC"]  = clang
+      RbConfig::MAKEFILE_CONFIG["CXX"] = clang
+    end
+  end
+  $CFLAGS << ' -DNOT_MACRUBY'
+end
+
+create_makefile('accessibility/key_coder')