AXTyper 0.7.4 → 0.8.0

data/.yardopts_typer

@@ -4,7 +4,6 @@
 --markup markdown
 --markup-provider redcarpet
 --readme README.typer.markdown
+--hide-void-return
 lib/**/*.rb
 ext/**/*{.m,.c}
--
-docs/KeyboardEvents.markdown

data/README.typer.markdown

@@ -1,10 +1,12 @@
 # AXTyper
 
-This gem is a component of AXElements. It provides an interface for
-posting keyboard events to the system as well as a mixin for parsing
-a string into a series of events.
+This gem is a component of
+[AXElements](http://github.com/Marketcircle/AXElements). It provides
+an interface for posting keyboard events to the system as well as a
+mixin for parsing a string into a series of events.
 
-## Demo
+
+## Quick Demo
 
 The basics:
 
@@ -30,21 +32,41 @@ Something a bit more advanced:
     end
 ```
 
-## Testing
+A more detailed demonstration of what this library offers is offered in
+[this blog post](http://ferrous26.com/blog/2012/04/03/axelements-part1/).
+
+
+## Documentation
+
+- [API documentation](http://rdoc.info/gems/AXTyper/frames)
+- The AXElements [keyboarding tutorial](https://github.com/Marketcircle/AXElements/wiki/Keyboarding)
+
 
-Running the AXElements test suite for only the AXTyper related tests
-can be accomplished with the `test:string` task.
+## Development
+
+Development of this library happens as part of AXElements, but tests
+and the API for this component should remain separate enough so that
+it can be released as part of the AXTyper gem.
+
+### Testing
+
+Running tests for this subset of AXElements is best done by using the
+`test:string` rake task, and also run `test:cruby` to make sure that
+some MacRuby specific code didn't sneak into the keyboarding
+component.
 
 ```shell
     rake test:string
+    rake test:cruby
 ```
 
-## TODO
+### TODO
 
 The API for posting events is ad-hoc for the sake of demonstration;
 AXElements exposes this functionality via `Kernel#type`. The standalone
 API provided here could be improved.
 
+
 ## License
 
 Copyright (c) 2012 Marketcircle Inc.

data/ext/accessibility/key_coder/key_coder.c

@@ -107,6 +107,13 @@ keycoder_post_event(VALUE self, VALUE event)
 void
 Init_key_coder()
 {
+  /*
+   *  Document-class: KeyCoder
+   *
+   *  Class that encapsulates some low level work for finding key code mappings
+   *  and posting keyboard events to the system.
+   *
+   */
   VALUE cKeyCoder = rb_define_class("KeyCoder", rb_cObject);
   rb_define_singleton_method(cKeyCoder, "dynamic_mapping", keycoder_dynamic_mapping, 0);
   rb_define_singleton_method(cKeyCoder, "post_event", keycoder_post_event, 1);

data/lib/accessibility/string.rb

@@ -5,10 +5,18 @@ require   'accessibility/key_coder'
 
 ##
 # Parses strings of human readable text into a series of events meant to
-# be processed by {Accessibility::Core#post:to:} or {KeyCoder.post_event}.
+# be processed by {Accessibility::Core#post} or {KeyCoder.post_event}.
 #
 # Supports most, if not all, latin keyboard layouts, maybe some
-# international layouts as well.
+# international layouts as well. Japanese layouts can be made to work with
+# use of `String#transform`.
+#
+# @example
+#
+#   app = AXUIElementCreateApplication(3456)
+#   include Accessibility::String
+#   app.post keyboard_events_for "Hello, world!\n"
+#
 module Accessibility::String
 
   ##
@@ -18,7 +26,7 @@ module Accessibility::String
   # {Accessibility::String::EventGenerator::CUSTOM}.
   #
   # For more details on event generation, read the
-  # {file:docs/KeyboardEvents.markdown Keyboard Events} documentation.
+  # [Keyboarding documentation](http://github.com/Marketcircle/AXElements/wiki/Keyboarding).
   #
   # @param [String]
   # @return [Array<Array(Fixnum,Boolean)>]
@@ -35,7 +43,7 @@ module Accessibility::String
   # @example
   #
   #   Lexer.new("Hai").lex          # => ['H','a','i']
-  #   Lexer.new("\\CAPSLOCK").lex   # => [["\\CAPSLOCK"]]
+  #   Lexer.new("\\CONTROL").lex    # => [["\\CONTROL"]]
   #   Lexer.new("\\COMMAND+a").lex  # => [["\\COMMAND", ['a']]]
   #   Lexer.new("One\nTwo").lex     # => ['O','n','e',"\n",'T','w','o']
   #
@@ -124,10 +132,13 @@ module Accessibility::String
     end
 
     # @private
+    # @return [String]
     SPACE         = " "
     # @private
+    # @return [String]
     PLUS          = "+"
     # @private
+    # @return [String]
     CUSTOM_ESCAPE = "\\"
   end
 
@@ -142,8 +153,8 @@ module Accessibility::String
   #   # Upper case 'A'
   #   EventGenerator.new(["A"]).generate  # => [[56,true],[70,true],[70,false],[56,false]]
   #
-  #   # Press the caps lock button, turn it on
-  #   EventGenerator.new([["\\CAPS"]]).generate # => [[0x39,true],[0x39,false]]
+  #   # Press the volume up key
+  #   EventGenerator.new([["\\F12"]]).generate # => [[0x6F,true],[0x6F,false]]
   #
   #   # Hotkey, press and hold command key and then 'a', then release both
   #   EventGenerator.new([["\\CMD",["a"]]]).generate # => [[55,true],[70,true],[70,false],[55,false]]
@@ -462,14 +473,19 @@ module Accessibility::String
     end
 
     # @private
+    # @return [String]
     EMPTY_STRING = ""
     # @private
+    # @return [Array(Number,Boolean)]
     OPTION_DOWN  = [58,  true]
     # @private
+    # @return [Array(Number,Boolean)]
     OPTION_UP    = [58, false]
     # @private
+    # @return [Array(Number,Boolean)]
     SHIFT_DOWN   = [56,  true]
     # @private
+    # @return [Array(Number,Boolean)]
     SHIFT_UP     = [56, false]
   end
 

data/lib/accessibility/version.rb

@@ -1,6 +1,8 @@
+##
+# The main AXElements namespace.
 module Accessibility
   # @return [String]
-  VERSION   = '0.7.4'
+  VERSION   = '0.8.0'
 
   # @return [String]
   CODE_NAME = 'Clefairy'

data/test/runner.rb

@@ -22,3 +22,17 @@ class MiniTest::Unit::TestCase
   end
 
 end
+
+
+# Figure out if we are testing a compiled version of AXElements, since some
+# tests will fail due to incomplete MacRuby features.
+RUNNING_COMPILED =
+  $LOADED_FEATURES.find { |file| file.match /ax_elements.rbo/ }
+
+def pid_for name # sneaky naming
+  NSWorkspace.sharedWorkspace.runningApplications.find do |app|
+    app.bundleIdentifier == name
+  end.processIdentifier
+end
+
+$LOAD_PATH << 'lib'

metadata

@@ -2,14 +2,14 @@
 name: AXTyper
 version: !ruby/object:Gem::Version
   prerelease: 
-  version: 0.7.4
+  version: 0.8.0
 platform: ruby
 authors:
 - Mark Rada
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-04 00:00:00 Z
+date: 2012-04-24 00:00:00 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -19,14 +19,14 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: "2.11"
+        version: "2.12"
   type: :development
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: "2.11"
+        version: "2.12"
 - !ruby/object:Gem::Dependency
   name: yard
   prerelease: false
@@ -71,7 +71,6 @@ extensions:
 extra_rdoc_files:
 - README.typer.markdown
 - .yardopts_typer
-- docs/KeyboardEvents.markdown
 files:
 - lib/accessibility/version.rb
 - lib/accessibility/string.rb
@@ -81,7 +80,6 @@ files:
 - test/runner.rb
 - README.typer.markdown
 - .yardopts_typer
-- docs/KeyboardEvents.markdown
 homepage: http://github.com/Marketcircle/AXElements
 licenses:
 - BSD 3-clause

data/docs/KeyboardEvents.markdown

@@ -1,122 +0,0 @@
-# Keyboard Events
-
-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.
-
-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.
-
-## Typing with the DSL
-
-The {Accessibility::DSL} mix-in exposes keyboard events through the
-`type` method. A simple example would look like this:
-
-    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
-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