AXElements 0.7.8 → 0.8.0

data/docs/NewBehaviour.markdown

@@ -1,151 +0,0 @@
-# Adding Behaviour
-
-Sometimes it is necessary to add extra methods to a UI
-element. There are a few cases of this in the AXElements source code
-itself, but many more opportunities exist. Unfortunately, extending UI
-element classes in AXElements is not totally straightforward. Some of
-the implementation details need to be understood before you can
-successfully extend AXElements.
-
-## Laziness
-
-In a laziness contest between AXElements and Garfield, AXElements
-wins (I assume). A lot of data that AXElements needs to be processed,
-such as name translation, and the work for this is delayed until it
-needs to be done in order to avoid a very large amount of overhead at
-boot time. Not all parts of AXElements are lazy, at least not yet.
-
-## Class Hierarchy
-
-At run time you will have noticed that you were returned objects which
-have a class like `AX::StandardWindow`, but you can never find the
-definition of the class in the source code. This is because the class
-hierarchy is lazily defined.
-
-### Deciding The Class Name
-
-The first thing to understand is the way that AXElements decides what
-class to instantiate for a UI element. This is actually pretty
-simple. Each UI element has a `role` attribute that is supposed to be
-used by assistive applications (read: AXElements) to understand which
-attributes will likely be available. This is Apple's hint as to what
-kind of class structure to choose.
-
-However, some UI elements also have a `subrole` attribute. For
-instance, `AXStandardWindow` is a subrole attribute that a UI element
-can have if it has a `role` of `AXWindow`. Once again, this is a hint
-that has been built into the system, and AXElements follows these
-hints. Put into object-oriented terms, if an object has a `subrole`,
-then that `subrole` becomes the class for the object and the `role`
-becomes the superclass; if the object does not have a `subrole`, then
-the class of the object will be decided by the `role`.
-
-### Abstract Base
-
-In either case, the {AX::Element} class will be an ancestor for the
-class that is chosen. A class that is its `subrole` will always have a
-superclass that is its `role`, and a class that is a `role` will
-always have {AX::Element} as its superclass.
-
-The advantage to creating this hierarchy is that it becomes much
-easier to implement searches that can find a "kind of" object. For
-instance, you can search for `text_fields` and find `AX::TextField`
-objects as well as `AX::SecureTextField` objects. This is one of the
-more powerful features outlined in the
-{file:docs/Searching.markdown Searching tutorial}.
-
-### Why Lazy?
-
-Laziness was chosen as it makes the library more resilient to custom
-roles and subroles. However, it also allows the MacRuby run time to
-boot faster since it avoids having to load all the different classes
-that would need to be defined.
-
-## Explicitly Defining Classes
-
-Now that you understand how classes are structured it should be very
-obvious how you should name your classes and choose your
-superclass. However, you could also use this technique to customize
-the hierarchy from what Apple has defined. For instance, you could force a
-`AXPopUpButton` to be a subclass of `AXButton` even though Apple has
-declared them to be separate roles. This may or may not be convenient
-depending on what custom methods you wish to add.
-
-## Reasons To Add A Custom Method
-
-For this topic I can only lead by example. Fortunately AXElements has
-a few examples to show off. The full list is in
-`lib/ax_elements/elements`, but I'll go over a few here.
-
-### Application Objects
-
-{AX::Application} has been extended in a couple of ways. First off, in
-order to provide an object oriented interface to sending keyboard
-events I added {AX::Application#type_string}.
-
-However, the big change with {AX::Application} is the merging of
-functionality from `NSRunningApplication`. In order to provide methods
-to set focus to an application I had to cache the
-`NSRunningApplication` instance at initialization and forward some
-method calls to that object. For instance, when you call `#set_focus`
-and pass an application object, AXElements does not actually using
-accessibility to set focus to the application, it uses the
-`NSRunningApplication` class internally still support the
-functionality in a transparent way.
-
-### Overriding `#==`
-
-The most popular customization to make is to overload `#==` for an
-object class that provides a more natural interface, and also one that
-makes search much more flexible. There is more than one example in
-this case, you could look at {AX::StaticText#==} which allows you
-check equality against a string that equal to the `value` attribute
-for the static text object. Similarly, {AX::Button#==} was added to
-check equality with buttons.
-
-### Table Rows
-
-When working with `AX::Table` objects you may have issues identifying
-children that belong to a specific column. Children of table rows, in
-my experience, do not have descriptions identifying which column they
-belong to. In cases where you have no unique identifier for a child,
-such as if you have multiple check boxes, there is no good way to find
-a specific check box using the built in search mechanics.
-
-You could hope that the column order never changes and just use the
-index of the children array but that is fragile; or perhaps you actually
-know what the order of the columns is to begin with and were able to
-keep track of how they changed.
-
-A much more sane way to identify the child is by identifying the
-column that the child belongs to. For instance, a the column for a
-table is an `AX::Column` object that usually has a `header` or `title`
-attribute which will be unique for the table. For this case,
-AXElements includes the {AX::Row#child_in_column} method which
-provides something similar to a search but with the few extra steps
-that would be necessary to correlate the child to the column and then
-return the child that you wanted.
-
-### More
-
-There are likely other cases that I have not come across yet which
-would be significantly simplified by a helper method or the merging of
-functionality from another class. Don't be afraid to share your
-extensions.
-
-## Tests
-
-If you are adding new features to AXElements then you should add tests
-for the new features and also make sure that you don't break existing
-features without realizing it.
-
-Running the test suite is covered in the {file:README.markdown}.
-
-Figuring out the test suite internals may not be easy, there is a bit
-of duplication, and something things need better organization. The
-test suite isn't well documented (on purpose) so you will have to read
-some of the other code to understand how things should work before
-writing your own tests. Be careful not to introduce state dependencies
-between tests or else you will not have a fun time tracking down why a
-certain test seems fail occassionally (which is a problem I had with
-notifications tests).

data/docs/Notifications.markdown

@@ -1,271 +0,0 @@
-# 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

@@ -1,250 +0,0 @@
-# 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.