AXElements 0.6.0beta1

data/docs/Notifications.markdown

@@ -0,0 +1,271 @@
+# Notifications
+
+@todo This document needs to be audited for accuracy. The interface
+for notifications is in flux and this document might be out of sync
+with the current implementation.
+
+Accessibility notifications are a tool that you can use to add a delay
+in script that waits until a certain event happens. These events could
+be a window being created, a menu being opened, or one of a plethora
+of other events.
+
+A notification is much more time efficient than simply using `sleep`
+to estimate how long an action will take to complete. Sleep often
+causes you to wait longer than is necessary to avoid waiting less time
+than what is needed. With notifications you set a maximum amount of
+time that should be waited, called the timeout, but waiting is stopped
+as soon as the notification is received. This makes using
+notifications preferable to simply sleeping.
+
+An important thing to understand is that an accessibility notification
+is separate from the notifications that are sent and received
+internally in a Cocoa app. Accessibility notifications are not very
+different in concept, they differ largely in mechanics. This is
+because talking to another application,
+[across processes](http://en.wikipedia.org/wiki/Inter-process_communication),
+is expensive and would be impractical to do for every notification
+that is sent internally in an application. This makes a bit more
+difficult to track down what notification is going to be sent through
+accessibility; using notifications more difficult than simply using
+`sleep`, at least until you have a lot of practice.
+
+## Simple Example
+
+Consider a log in window. You enter some credentials and then you
+press a button to log in and load up the main application window.
+This procedure is most likely asynchronous, it usually takes one or
+two seconds, but could take longer. To script logging in you would
+have to wait until the main application window loaded. You could just
+use `Kernel#sleep`, but how long should you sleep for and how reliable
+is that? How much time would that waste?
+
+Notifications are perfect for this scenario; whenever a window is
+created, the application sends out a notification to any accessibility
+applications that are listening letting them know a window was
+created; the notification will even include the object that sent the
+notification and the name of the notification. Using this system, we
+can just wait for the notification to be received and continue
+executing the script right away (technically, there can be few
+milliseconds of delay). A typical example of using notifications looks
+like this:
+
+     register_for_notification app, :window_created
+     login # trigger an action that will eventually send a notification
+     wait_for_notification
+
+And that's it.
+
+## One-Two-Three Combo
+
+Using notifications is a three step process: first a left jab to set up
+the notification, then you dodge the counter punch, and then you
+finish with a right cross to wait for the notification. If you're left
+handed then you can jab with the right and cross with the left (but
+you still setup first and then wait).
+
+### First You Set It Up
+
+Setup is the important step and is fairly painless as far as what
+you need to provide for AXElements. To register for a notification you
+call {Accessibility::Language#register_for_notification}. You pass the
+the {AX::Element} who will be sending the notification and then the
+notification name. Another simple example would be:
+
+    register_for_notification text_field, :value_changed
+
+In this hypothetical case, we want to wait for a `:value_changed`
+notification that will be sent by `text_field`. That's it. And that
+also covers 90% of the cases where you will use notifications.
+
+#### Applications Are Special
+
+Listening from the application, an {AX::Application}, object is a
+special case. When you say that an {AX::Application} object will be
+the sender, what you are saying is that any UI element in the app will
+be the sender and you don't really care as long as you get the right
+notification name (that's not entirely true, but a good enough lie for
+now).
+
+#### Notification Names or: How Is Babby Formed?
+
+Like attribute and action name translation, notification names are
+also translated for your convenience. However, where do you get the
+notification names that Apple provides?
+
+It turns out that there is no API for getting a list of notifications
+that an element can send---Apple dropped the ball in this case, but
+they did provide a
+[list of notifications](http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/Accessibility_RoleAttribute_Ref/Notifications.html#//apple_ref/doc/uid/TP40007870-Notifications-SW1)
+which has been nicely updated for Mac OS X Lion. The list of
+notifications is __required__ reading if you want to use accessibility
+notifications.
+
+For custom notifications, which I'll get to in a bit, you shouldn't
+(read: don't) do a name translation unless you provide an equivalent
+constant for the MacRuby run time. Instead, you should just provide
+the string with the notification name:
+
+     register_for_notification app, 'customNotification'
+     register_for_notification app, 'Cheezburger''
+
+### Do Something
+
+To trigger the action, you perform an action. This was already covered
+in the {file:docs/Acting.markdown Acting tutorial}, which is probably
+why you are reading this tutorial.
+
+### Waiting...
+
+Once the action has been triggered, you simply need to wait for the
+notification to be received:
+
+    wait_for_notification
+
+And then you wait (if you are the computer or just enjoy watching your
+scripts execute). If all goes well you will receive the notification,
+and the script continues on to the next statement. By default,
+AXElements will wait for 10 seconds, and if the notification is not
+received then the script will continue anyways.
+
+Waiting for longer, or less, time than the default can be done by
+passing a parameter to `wait_for_notification`. For instance, you
+could wait for a minute or a second:
+
+    wait_for_notification 60.0
+    wait_for_notification 1.0
+
+## A Bit More Complicated
+
+The above should cover most cases, but notifications can be more
+complex than those examples. You might need to unregister for
+notifications, or add more complex logic to a notification
+registration.
+
+### Unregister Notifications
+
+If you need to unregister for a notifications then you can. The DSL
+layer provides {Accessibility::Language#unregister_notifications}, and
+hopefully more options in the future.
+
+Using `unregister_notifications`, you can unregister _all_
+notifications. This is actually done in cases where a notification is
+not received, simply to clear out possible problems with lingering
+registrations that might mess up future waiting.
+
+### You Are The Decider
+
+When you setup a notification you can optionally pass a block that
+decides whether or not the received notification is the one you
+wanted. You will be given the element that sent the notification,
+which is not necessarily the element that you registered with, and the
+name of the notification. In this case you would register for a
+notification like so:
+
+    register_for_notification app, :window_created do |window, notification|
+      window.title == 'New Contact'
+    end
+
+This gives you some extra security. Instead of continuing the script
+execution after getting the first `:window_created` notification, the
+script will remain paused until the element that sends the
+notification has a title of `'New Contact'`.
+
+The contract is quite simple. If you do not pass a block, then the
+first notification received will cause AXElements to stop waiting; if
+you want to pass a block then the block must return tuthy or falsy
+to decide whether the received notification is the one that you
+wanted. You will be given the sender of the notification as well as
+the notification name; though the notification name will usually not
+be very interesting since it is the value you registered with.
+
+### More Than One Notification
+
+You can register for as many notifications as you want, but I don't
+recommend that you register for more than one at a time unless you
+know what you are doing. The reason why is that when you call
+`wait_for_notification`, you are pausing script execution until any of
+the notifications you have registered for are received. The block that
+you pass will only be used for notifications that are sent to the
+registration you set it up with.
+
+This is why AXElements unregisters everything if it fails to receive a
+notification. This detail might also screw you over if you are trying
+to work with more than one notification at once and should be fixed in
+the future.
+
+### Rainbows And Unicorns
+
+As mentioned earlier, accessibility notifications are not all rainbows
+and unicorns. If you've played with notifications while going through
+this tutorial then you may have noticed a problem or two with the
+design.
+
+#### Who Sends The Notification
+
+Documentation is the only hint you really get about who will send
+particular notifications. If you are confident that a certain
+notification will be sent but do not know who will be sending the
+notification, then you can register with the {AX::Application} object
+to be the sender of the notification. This causes you to receive
+notifications from any object as long as it has the proper
+notification type. If you use this feature in conjunction with passing
+a block that always returns false, then you can capture all the
+notifications for a period of time and find out who is sending the
+notification. An example would look something like this:
+
+    register_for_notification app, :value_changed do |element, notif|
+      puts element.inspect
+      false
+    end
+
+    # trigger some action
+
+    wait_for_notification 30.0
+
+Since you are returning `false` at the end of the block, the script
+will pause until a timeout occurs and you will see the `#inspect`
+output for each object that sends the notification.
+
+### What Is Known To Work
+
+- `:value_changed` is only sent by objects that have a `value`
+  attribute, and should be sent every time that the value is changed,
+  whether through accessibility or normal computer usage
+- `:menu_opened` seems to only be sent by menu bar menus, not by menus
+  opened by pop up buttons
+
+## Custom Notifications
+
+Custom notifications are pretty simple. Apple recommends that you try
+to use the built in notifications as much as possible, but
+acknowledges that you may need to add your own notifications
+sometimes.
+
+As noted earlier, accessibility notifications use a different system
+than cocoa notifications; accessibility notifications are much simpler
+to send; it is simply a C function call with two parameters:
+
+    NSAccessibilityPostNotification(self, @"Cheezburger");
+
+The first parameter is the sender of the notification; just as with
+other accessibility APIs from the server (read: app) side of things,
+you pass the actual object and accessibility magic will create the
+token to send to the client (read: AXElements). The one caveat in this
+case is that the sender of the notification cannot be an object that is
+ignored by accessibility or else the notification will not be sent. If
+you are unsure whether or not the object is visible to accessibility,
+then you need to call an extra function to find someone who _will_ be
+visible to accessibility; these functions are listed in the
+[AppKit Functions](http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/ApplicationKit/Miscellaneous/AppKit_Functions/Reference/reference.html#//apple_ref/doc/uid/TP40004154)
+in the Accessibility section. An example would look like this:
+
+    NSAccessibilityPostNotification(NSAccessibilityUnignoredAncestor(self), @"Cheezburger");
+
+In this case you would be looking up the hierarchy for an ancestor,
+but you could also look down the hierarchy for a descendant or to the
+side for a sibling.
+
+As a rule of thumb, if you end up spending more 20minutes trying to
+figure out which notification will should be listening for, and who
+will be sending it, then you should just create a custom
+notification. But you don't have to take my word for it.

data/docs/Searching.markdown

@@ -0,0 +1,250 @@
+# Searching
+
+Searching the view hierarchy is the most powerful idea that this
+toolkit provides by _significantly_ simplifying the process of
+describing UI elements. Search works by looking at the child elements
+of the current element, and possibly at the grandchildren, and so on
+and so forth in a breadth first searching order. There are a few well
+defined features of searching that make it powerful: pluralization,
+attribute filtering, nesting, and element attribute inference.
+
+## Search Basics
+
+First, the basic form of a search looks like this:
+
+    $ELEMENT.$KLASS($FILTER_ATTRIBUTE1: $FILTER_VALUE1, ...)
+
+Actually, that is just the form for an implicit search, which is a
+little nicer to write than an explicit search. The only difference
+between the two is that an implicit search must always find something,
+since we are treating it as a description, or else a
+{AX::Element::SearchFailure} error will be raised.
+
+Looking at the pieces of the statement, the obvious piece is
+`$ELEMENT`; `$ELEMENT` is the element to start searching from. Then
+`$KLASS`, the method name, is the class of the object to search for,
+and the parameter list is just a hash where the key,
+`$FILTER_ATTRIBUTE`, is an attribute on the instance of the class and
+the value, `$FILTER_VALUE`, needs to match what is returned when the
+attribute is looked up.
+
+An implicit search is written as if the class of the object you were
+searching for was the method and the filters would be the parameters
+for the method. If we substitute real values in, an example would like
+this:
+
+    window.button(title: 'Main Window')
+
+Which means that we want to find a `button` that is a child (or
+descendant) of `window`, but only if the `button` has a `title` of
+`'Main Window'` on it. You can add as many filters as you want, but
+generally you will only need one.
+
+### Pluralization
+
+In cases where you want to find more than one object of a certain
+type, you simply need to pluralize the method name. For example:
+
+    window.buttons
+
+is translated into something like this:
+
+![All The Buttons](images/all_the_buttons.jpg)
+
+It's just that easy. The rules for pluralization are the same as
+English (or the local language?) since we are using the
+`ActiveSupport::Inflector` to do the work of translating from
+pluralized form back to the singular form. Even something like 'boxes'
+will get translated back to 'box' and work as you expect.
+
+Except for the fact that you will get a collection of UI elements back
+instead of a single item, pluralized search works the same as a
+non-pluralized search. You can attach any filters you could use with a
+non-pluralized search, and if the search is implicit then it must find
+something.
+
+Pluralized searches are useful when you want to do some custom
+refinement on a search, or if you need to make sure something is not
+in the UI element tree (and hopefully that means it is not on the
+screen anymore either). It can also be helpful when you want to
+explore the UI element tree and find out what types of UI elements are
+present on the screen. The detail to remember is that a pluralized
+search will have to explore the entire UI sub-tree from the starting
+point and so it could be slow.
+
+### Kind Of
+
+Remember earlier when I said the method name should be the class of
+the element being searched for? Well, that was kind of a lie. Kind of.
+Get it? Have I killed the joke yet? Kind of? :D
+
+The search class that you enter is actually matched using `#kind_of?`
+instead of matching the classes exactly. And since class hierarchies
+are properly setup, you can search for a base class and end up finding
+subclasses.
+
+For instance, not all buttons are of the class `AX::Button`, the
+traffic light buttons are all different subclasses of `AX::Button`:
+`AX::CloseButton`, `AX::MinimizeButton`, and `AX::ZoomButton`. There
+are other several other subclasses of `AX::Button` as
+well. `AX::Button` itself is a subclass of `AX::Element`. Actually,
+all UI elements are a subclass of `AX::Element`. What this means is
+that when you have code like:
+
+    app.close_button
+
+You will only ever find something that is a `AX::CloseButton`, but
+when you write something like:
+
+    app.button
+
+Any button or subclass of button, including all the traffic light
+buttons, can be found. I believe this makes search follow the
+[DWIM](http://en.wikipedia.org/wiki/DWIM) principle, and allows you to
+shorten the code you need to write in a number of cases. For example:
+
+    app.window
+
+Can be substituted in place of
+
+    app.standard_window
+
+to find the first window for `app`. This makes sense if there is only
+one window for the app, which is often the case. Similarly, if you are
+searching from a container, such as an `AX::Group`, which only has a
+one button, which happens to be a `AX::SortButton`, then you can say:
+
+    table.button
+
+Since it will not be ambiguous and AXElements knows what you
+mean. What if we take it a step further, what if made an even broader
+search. Since _all_ UI elements are a subclass of {AX::Element}, we
+could just write something like:
+
+    app.element
+
+Which would find the first child of `app`. If we combined this with
+pluralization, we could do something like:
+
+    app.elements
+
+Which will return an array with _all_ the descendants in it; so as always
+you will need to have some awareness of the layout of the element tree
+when you write a search. Otherwise you could end up finding something
+completely different from what you wanted; consider what could happen
+if you search for an `AX::Button` objects when you want an
+`AX::CloseButton`. In these cases you will want to be more specific
+about what you are looking for, which can often allow you to skip the
+need for a search filter. Be specific when it sounds better and
+generalize more when you can, it should make code read more
+naturally.
+
+### Nested Searching
+
+Sometimes you need to describe an element on the screen, and the only
+reasonable way to do so is by describing some of the descendants of the
+element that you are looking for. For this requirement, nested
+searching exists, and very naturally too. Pretend that you didn't
+already look at the next code snippet and try to guess what a nested
+search looks like; you will probably be correct. __Hint__: Searches
+can be nested arbitrarily deep and mixed in with other filter
+parameters. The answer, by example:
+
+    window.outline.row(text_field: { value: 'Calendar' })
+
+This would be asking for the outline row that has a text field with
+the value of `'Calendar'`. The proper form for this would be:
+
+    $ELEMENT.$KLASS($DESCENDANT: { $DESCENDANT_FILTER_ATTRIBUTE: $DESCENDANT_FILTER_VALUE1, ... }, ...)
+
+Where `$DESCENDANT` plays the same role as `$KLASS`, but for a new
+search that will be applied to descendants of `$KLASS`. Nested
+searching is a feature you won't need too often if the UI hierarchy
+makes good use of identifiers or other attributes that can be used to
+uniquely identify an element. Nested searching is best used when you
+can only identify an element by describing its children. But you don't
+have to take my word for it.
+
+### Element Attribute Inference
+
+Element attribute inference came about because of a coding error, when
+someone was trying to write some code to search for element that
+matched to a title UI element. Before going over the solution I think
+it would be best to explain the problem.
+
+If an element has a title UI element attribute, then the title UI
+element will end up being another UI element. The problem with this is
+that you then need to know about that element before you search and
+then you need to use the element as the filter value, for example:
+
+    title_field = window.text_field(value: 'Name')
+    window.button(title_ui_element: title_field)
+
+While that code is legitimate, it is not the most succinct way of
+writing what was meant, and maybe not as clear as it could be. Perhaps
+something more like:
+
+    window.button(title_ui_element: 'Name')
+
+In this case you are matching the `title` of the
+`title_ui_element`. This works without introducing inconsistencies in
+the language we have created for searching. In the example, you would
+be saying that the button you are looking for will be associated with
+a title UI element that says `'Name'`. You can still match against the
+actual UI element if you want, but I think this is much simpler.
+
+This is not actually implemented internally to the searching
+logic, it is implemented in each class that wants to
+participate. Since search works by getting the value of the search
+filter and checking if it is `==` to the filter value, we just need
+to implement `==` on specific classes where we want to support custom
+behaviour. Examples of how this would work would be
+{AX::StaticText#==} and {AX::Button#==}. The behaviour could be easily
+added to other classes where it made sense. However, this type of idea
+can be further expanded to cases that might not be so easily
+implemented and is discussed in future prospects.
+
+## Explicit Search
+
+In the off chance that you need to make an explicit search, you can
+trigger a search through {AX::Element#search}. In this case you give
+the `$KLASS` as the first parameter of the method and the filters are
+the remaining parameters. As with {AX::Element#attribute}, this is
+meant for performance in cases of heavy searching; you should avoid
+using it unless you know what you are doing.
+
+## Caveats
+
+The only caveat to note right now is that a UI element will always
+return `false` when you ask if it can `#respond_to?` something that
+would be an implicit search. This is because of the semantics of a
+search do not make sense in the context of `#respond_to?` and would be
+very expensive. You would need to perform the search in order to know
+if the search would succeed.
+
+## The Future
+
+Right now, the only case that is not handled is filtering by
+parameterized attribute. The problem with this case is that I am not
+sure how to work it into the existing syntax or how to change the
+existing syntax. Since you also need to encode the parameter with the
+attribute it is difficult to express in terms of key-value
+pairs. Perhaps the key could be an array so that the attribute can be
+included with the key? That would be possible without too much work,
+but how would it look? Does the syntax for search start to get too
+crazy at that point? For instance, you cannot use the label syntax for
+hash keys with an array (unfortunately), so code would look like:
+
+    window.button([:string_for_range, CFRange.new(0,5)] => 'AXEle')
+
+This topic is open to debate, but I will always play the part of the
+devil's advocate. :)
+
+### Inference
+
+There is also space for enhancement in the attribute inference
+feature(s). Wouldn't it be nice to be able to specify a filter value
+as a range instead of a specific value? Probably not very often, but it is
+something that could be done. Search filtering is not very flexible in
+that regard right now, and maybe it never needs to be, but it is an
+interesting change to think about.

data/docs/TestingExtensions.markdown

@@ -0,0 +1,52 @@
+# Test Helpers
+
+@todo Pretend that this does not exist yet
+
+There are some types of assertions that you would like to make during
+testing that simply does not make sense using the build in
+assertions. These can include things like existence checks which you
+would have to implement by searching, or ... that is really the only
+one I have so far :)
+
+## RSpec
+
+RSpec 2 is the Marketcircle choice for implementing functional and
+behavioural tests for apps using AXElements. It is great and offers
+the flexibility and features that make using it very good for large
+test suites.
+
+You can load the RSpec matchers that AXElements adds by requiring
+
+    require 'rspec/ax_elements'
+
+### Existence
+
+Checking for the existence of an object in RSpec with AXElements looks
+a bit awkward:
+
+    window.search(:button).should be_empty
+    # or
+    window.search(:button).should_not be_empty
+
+That does not communicate intent as clearly as it could. What if you
+could say something like:
+
+    window.should have_a :button
+    # or
+    window.should_not have_a :button
+
+What if you have filters? Well, that is handled as well, though maybe
+not as nicely:
+
+    window.should have_a(:button).with(title: 'Hello')
+
+## Minitest
+
+AXElements uses minitest for its own regression test suite. Minitest
+is pretty cool, and there is good cause to support it as well. To that
+end, we have provided the equivalent assertions.
+
+You can load it like so:
+
+    require 'minitest/ax_elements'
+

data/docs/images/ui_hierarchy.dot

@@ -0,0 +1,34 @@
+digraph {
+        Application  [label = "Application: Mail", style=filled]
+        MainWindow   [label = "MainWindow: Inbox"]
+        Outline      [label = "Outline"]
+        Table        [label = "Table: Emails"]
+        TableRow1    [label = "TableRow: Spam"]
+        TableRow2    [label = "TableRow: Daily LOLcat"]
+        MenuBar      [label = "MenuBar", style=filled]
+        MenuBarItem1 [label = "MenuBarItem: File", style=filled]
+        MenuBarItem2 [label = "MenuBarItem: Edit"]
+        MenuBarItem3 [label = "MenuBarItem: Help"]
+        Menu1        [label = "Menu", style=filled]
+        MenuItem1    [label = "MenuItem: Preferences"]
+        MenuItem2    [label = "MenuItem: Services", style=filled]
+        MenuItem3    [label = "MenuItem: Quit"]
+        Menu2        [label = "Menu", style=filled]
+        MenuItem4    [label = "MenuItem: Services Preferences", style=filled]
+
+        Application  -> MainWindow
+        Application  -> MenuBar
+        MainWindow   -> Outline
+        MainWindow   -> Table
+        Table        -> TableRow1
+        Table        -> TableRow2
+        MenuBar      -> MenuBarItem1
+        MenuBar      -> MenuBarItem2
+        MenuBar      -> MenuBarItem3
+        MenuBarItem1 -> Menu1
+        Menu1        -> MenuItem1
+        Menu1        -> MenuItem2
+        Menu1        -> MenuItem3
+        MenuItem2    -> Menu2
+        Menu2        -> MenuItem4
+}

data/ext/key_coder/extconf.rb

@@ -0,0 +1,6 @@
+require 'mkmf'
+
+$CFLAGS << ' -std=c99 -fobjc-gc -Wall -Werror'
+$LIBS   << ' -framework Cocoa -framework CoreServices -framework Carbon'
+
+create_makefile('key_coder')