AXElements 0.7.8 → 0.8.0

data/docs/Debugging.markdown

@@ -1,165 +0,0 @@
-# Debugging
-
-This document includes instructions on using AXElements' built in
-tools to help you debug issues with your scripts, or in cases where
-you might find a bug in AXElements itself or MacRuby.
-
-## Visibility
-
-Sometimes an object that should be visible to accessibility does not
-show up. Sometimes it will be invisible to the Accessibility Inspector
-and sometimes it will be invisible to AXElements. This is because the
-inspector uses hit testing to find objects and AXElements uses the
-`children` and `parent` attributes (usually). Depending on which part
-of the accessibility protocol is not being implemented correctly, one
-or both tools might fail to work.
-
-Fortunately, failures in the accessibility API are few and far
-between. The one big,
-[known issue](http://openradar.appspot.com/6832098) is with menu bar
-items; you cannot work around this issue without hacking into private
-Apple APIs. Specifically, you would need to override built in
-accessibility methods in the class that implement the user interface
-for NSStatusItem, which is a private class; or you could build your
-status bar item as an NSMenuExtra, which is another private class. You
-can find more tips on augmenting accessibility for apps in the
-{file:docs/AccessibilityTips.markdown Accessibility Tips} document.
-
-## Trees
-
-Sometimes you need to see the big picture, the whole UI tree at
-once or at least be able to see the root of the hierarchy from where
-you are. For these troubling cases AXElements provides a few tools.
-
-### Text Tree
-
-Printing a text tree is similar to how a UI dump works with
-accessibility on iOS. AXElements does improve a bit on its iOS
-equivalent. Simply using the Accessibility Inspector does not give you
-a good picture of the whole tree and with complicated structures it is
-easy to make mistakes navigating the UI tree.
-
-The text tree comes formatted for you, and you can simply print it out
-to the console. The output uses indentation to indicate how far down
-the tree each element is, and the first element up the tree with one
-indentation level less will always be the parent for an element.
-
-Printing out a text tree in the console is very easy. First you generate
-the text dump and then you print it out:
-
-    puts Accessibility.dump(app)
-
-This method is useful when you are having difficulties with
-search. Sometimes when searching you will end up finding the wrong
-element because your search query was ambiguous and you didn't
-know at the time. Printing out a dump can often be all the help you
-need in order to identify your problem.
-
-However, if the standard `#inspect` isn't doing it for you, you can
-perform your own inspection every element in a tree yourself using the
-built in enumerators. Searches use the {Accessibility::BFEnumerator},
-but the text tree dump method uses {Accessibility::DFEnumerator}.
-
-### Dot Graph
-
-For super fancy text trees, AXElements can generate dot graphs for
-consumption by [Graphviz](http://www.graphviz.org/). In this case, you
-want to call {Accessibility.graph} and pass the root of the tree you
-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
-between the cracks. However, it's also possible that the problem is
-actually how accessibility information is being vended out.
-
-As an example, Radar #10040865 is a ticket that I filed with Apple
-where they broke accessibility with search fields. The effect to
-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, I have provided
-some tools to help you along the way.
-
-## All The Way Up
-
-Sometimes you don't need a whole tree to be printed out. Sometimes
-just seeing the path from an element to the top level element is
-enough. {Accessibility.path} is your friend in this case, it will
-provide you with an array of UI element objects, each successive
-element will be the parent of the previous element. This is almost
-like the view that the Accessibility Inspector provides.
-
-## Custom Exceptions
-
-AXElements provides some customized exceptions in the OO layer that
-should help give you much better hints at what went wrong when you
-have a problem.
-
-Custom exceptions have been created to help identify the point of
-failure that would have caused a more cryptic exception to have been
-raised instead. These custom exceptions also capture more metadata
-about the problem that occurred which should give good hints as to what
-went wrong.
-
-### Search Failures
-
-An {AX::Element::SearchFailure `SearchFailure`} will occur when you
-perform an implicit search that fails to find anything.
-
-In cases where implicit searches are chained, which happens frequently
-with deep UI hierarchies, if one of the searches were to fail then you
-would receive a `NoMethodError` about something having
-failed. Sometimes the failure would happen because the search returned
-`nil`, and of course `nil` would not respond to another search, though
-this problem was easy to identify if you are familiar with the
-AXElements source code; in other cases the failure would occur
-somewhere in the search {Accessibility::Qualifier qualifier} or in the
-{Accessibility::BFEnumerator enumerator}, and it was not always clear why.
-
-The other feature of a search failure is that the exception message
-will include an element back trace using {Accessibility.path}. This is
-meant to give a hint about why the search failed.
-
-### Attribute Not Writable
-
-You will receive {AX::Element::ReadOnlyAttribute `ReadOnlyAttribute`}
-exceptions only when you try to set an attribute that is not
-writable. Again, this was originally designed to more easily identify the
-point of failure when you try to write to an attribute that you should
-not write to.
-
-Specifically, `set_focus` is called by methods internally by
-AXElements and at one time it was causing some problems when elements
-were unexpectedly not allowing their `focused` attribute to be
-written.
-
-## Logging
-
-The core level of AXElements has logging in every case that an error
-code is returned. Though, it can show false positives because of
-hiccups in the accessibility API or implementation that an app
-provides; so it turned off by default. This feature is also going away
-in favour of more intelligent error handling in the core wrapper.
-
-When weird bugs are occuring, possibly even crashing MacRuby, you
-should try turning on the logs and then trying the script again. You
-might see some tell tale logs printed out right before the crash. You
-can turn on logging right after you load AXElements, like so:
-
-    require 'ax_elements'
-    Accessibility.log.level = Logger::DEBUG
-
-The standard log levels are available, the full set is available
-[here](http://rdoc.info/stdlib/logger/1.9.2/Logger/Severity). `Logger::DEBUG`
-will turn on all logs.

data/docs/Inspecting.markdown

@@ -1,261 +0,0 @@
-# Inspecting The User Interface
-
-When it comes to inspecting the user interface there are _many_ nooks
-and crannies that are interesting to talk about. This document covers
-the core concepts that you will need to understand before you can
-begin discovering them yourself.
-
-## The UI Tree
-
-The first most important thing to understand is that accessibility
-exposes the user interface as a hierarchy of user interface
-tokens. Each token references a GUI element on screen, either
-something literal like a button, or something structural like a group
-of buttons. The organization of the hierarchy should make sense to
-human beings since it is designed to be used by the disabled, so it
-does not nescesarrily match the underlying organization of views and
-can be completely arbitrary. That being said, most apps will use the
-defaults provided by AppKit and "Just Work"™ the way you would
-expect.
-
-Throughout this documentation I will refer to tokens as if they were
-the object themselves unless otherwise noted. It's much easier Each
-token object knows who its parent object is, and knows about any
-children objects that it may have. thus creating a tree structure. At
-least this is the theory, but there are, on occasion, some hiccups
-since accessibility is a protocol to which multiple parties have to
-conform.
-
-A sample hierarchy might start with the application, which has a menu
-bar as one of its children and the menu bar has menu bar items, each
-menu bar item has a menu and each menu has menu items; some menu items
-have another menu as its child which then leads to more menu items and
-so on. This hierarchy is much easier to understand once visualized:
-
-![Example GUI Hierarchy](images/ui_hierarchy.png)
-
-This example is meant to be instructive, the menu bar is one of the
-more complicated hierarchies to navigate and many other nodes in the
-hierarchy have been left out. The good news is that AXElements has
-techniques and patterns for simplifying navigation, so don't get
-scared off just yet. The point here is that each menu item knows which
-menu is its parent, and each menu knows which menu item or menu bar
-item is its parent, and the menu bar knows that which application is
-its parent. But who is the parent of the application? It turns out
-that that is a trick question, an application does not have a
-parent. An application is the entry point for the UI hierarchy, it
-will be the place where a script usually starts and application
-objects can be created using the {Accessibility} singleton
-methods. You can create the object for an application that is already
-running using {Accessibility.application_with_name} like so:
-
-    app = Accessibility.application_with_name = 'Finder'
-
-### Accessibility Inspector
-
-To quickly navigate through the UI tree, Apple has provided a tool,
-the Accessibility Inspector, as part of the Developer Tools. The
-inspector will come in handy when you are writing scripts using
-AXElements, though there are some potential pitfalls that will be
-discussed later.
-
-Once you install the Developer Tools, the inspector can be found in
-`/Developer/Applications/Utilities/Accessibility Tools/`. It is worth
-playing around with the inspector to get a feel for what the
-accessibility APIs offer; but keep in mind that the inspector is a
-dumb interface to the accessibility APIs.
-
-## Attributes
-
-Each item in the GUI tree has attributes; buttons have a title,
-sliders have a value, etc.. Pointers to the parent and chilrden nodes
-are also attributes. Programmatically, you can get a list of
-attributes that an object has by asking nicely. AXElements exposes
-this API via {AX::Element#attributes}. {AX::Element} actually acts as
-the abstract base class for all objects, encapsulating everything that
-the accessibility APIs offer.
-
-### Accessing Attributes
-
-Every attribute can be accessed as a method of the UI object. The
-method name will always be the
-[snake_case](http://en.wikipedia.org/wiki/Letter_case) version of the
-attribute name without the prefix.
-
-Some examples:
-
-- `AXChildren` would become `children`
-- `AXMainWindow` would become `main_window`
-- `AXIsApplicationRunning` would become `application_running?`
-
-The last case is special because we consider "`Is`" to be part of the
-prefix and the method name has a "`?`" at the end. This is to follow
-Ruby conventions of putting "`?`" at the end of the method name if the
-method is a predicate. There will be more details about these rules in
-other tutorial documents, but this is really something that should be
-abstracted away. This detail is not hidden right now becaues the
-Accessibility Inspector does not hide the information and you still
-need to understand it in order to use the inspector with AXElements.
-
-#### Example
-
-We can demonstrate how this all comes together with a small
-example. In the terminal, you can start up a console session of
-AXElements by loading `ax_elements` in `macirb` or by navigating to
-the AXElements repository and running the `console` task if you have a
-clone. Then you can try the following code, one line at a time:
-
-    app    = Accessibility.application_with_name 'Terminal'
-    window = app.main_window
-    title  = window.title
-    puts "The window's title is '#{title}'"
-
-In the first line, we are creating the object for the application. As
-mentioned earlier, you will usually start navigating the UI tree from
-the application object. Giving the name of the application is the
-easiest way to create an application object but requires the
-application to already be running.
-
-On the second line we use the application object and ask it for the
-value of the `main_window` attribute. This will return to us another
-UI object, this time for the window. You will also notice that the
-console printed out some extra information about the window, such as
-the title of the window and its position (in flipped
-coordinates). Each UI element has implemented the `#inspect` method in
-such a way as to provide users with a succinct but useful way to
-identify the UI element on the screen, and `macirb` is designed to
-happily print that information out for each statement that you enter.
-
-On the third line, we ask the window for it's `title`, and it gives
-us back a string which we then print out on the fourth line. Notice
-that the title of the window was also printed by the console as part
-of the `#inspect` output that `macirb` asks to print out.
-
-### Inspect Output
-
-Using `#inspect` is a great way to see the important details of a UI
-element, it shows the values of the most important attributes so that
-you can quickly identify which element it really is on screen, but not
-so many details that it becomes a pain. A typical example of
-`#inspect` output looks like this:
-
-    #<AX::StandardWindow "AXElementsTester" (1584.0, 184.0) 17 children focused[✘]>
-
-That output includes all the pieces that you will normally see from
-`#inspect`, but you may see less or more depending on the UI element
-that is being inspected. As is the norm in Ruby, you will always at
-least get the name of the class; then AXElements will try to include a
-piece of identifying information such as the `title`, then you have
-numbers in parentheses which are the screen coordinates for the
-object, then you have the number of children, and then check boxes for
-boolean attributes. Aside from the class name, the other pieces of
-information will only be included if they are relevant, and certain
-objects will also include other information.
-
-The values shown by `#inspect` are pieced together using helper
-methods from the {Accessibility::PPInspector} module. {AX::Element}
-implements a generic implementation with
-{AX::Element#inspect}. However, the generic `#inspect` may not always
-choose the best attributes to show. An example would be
-{AX::Application#inspect}, which overrides the generic `inspect` so
-that the process identifier for the application is also included. In
-other cases, the screen co-ordinates or whether the element is enabled
-may not be relevant, so you can override the method in the specific
-subclass to not include those attributes and/or include other
-attributes. The key idea is to make `#inspect` helpful when exploring
-a UI through the console or when debugging a script.
-
-## Accessing Children
-
-Following first principles shown in the example from above you might
-be led to believe that in order to navigate around the UI tree you
-will have to write code that looks something like this:
-
-    app.main_window.children.find do |child|
-      child.class == AX::Button && child.title == 'Add'
-    end
-
-However, AXElements provides a way to specify what you want that is
-much more convenient to use. Behold:
-
-    app.main_window.button(title: 'Add')
-
-This is quite the simplification! If we break it down, you see that
-the method name is the class of the object you want, and then if you
-need to be more specific you can pass key-value pairs where the key
-is an attribute and the value is the expected value. The above example
-says "find a button with the title of 'Add'".
-
-You can use as many or as few key-value pairs as you need in order to
-find the element that you are looking for. If you do not specify any
-key-value pairs, then the first object with the correct class will be
-chosen. The {file:docs/Searching.markdown Searching Tutorial} goes
-into more depth on how key-value pairs are used to specify which
-object you want.
-
-## Parameterized Attributes
-
-There is a special type of attribute that is called the parameterized
-attribute. The difference from a regular attribute is that you need to
-supply a parameter. An example of this would look like this:
-
-     static_text.string_for_range CFRange.new(0,5)
-
-The method name suggests that you need to provide a range and in
-return you will be given part of the string that corresponds to the
-range. Of course, this example is quite contrived since string slicing
-is so trivial in Ruby (but this parameterized attribute actually exists).
-
-Parameterized attributes are different enough from regular attributes
-that Apple does not want them mixing together and producing
-offspring. AXElements is a bit progressive, but still keeps the list
-of parameterized attributes separate from attributes; you can get a
-list of parameterized attributes for an object with
-{AX::Element#param_attributes}. Similarly, you have probably already
-noticed that parameterized attributes have their own section in the
-Accessibility Inspector and that many objectss do not have any
-parameterized attributes.
-
-In my experience, parameterized attributes have not been very useful,
-but I haven't looked hard enough and am still looking for a good
-example to put in this section of the tutorial.
-
-## Explicit Attribute Access
-
-In cases where you know what you want is going to be an attribute, you
-can get better performance from accessing attributes by calling
-{AX::Element#attribute} and passing the attribute name.
-
-    app.attribute(:main_window)
-
-Similarly, for parameterized attributes, you need to call
-{AX::Element#param_attribute} and pass the attribute name and
-parameter as parameters to that method.
-
-    app.param_attribute(:string_for_range, CFRange.new(0,5))
-
-These methods are exposed so that other library classes can achieve
-better performance; but you should avoid using them regularly. These
-APIs may be hidden in the future in order to enforce the DSL usage.
-
-## Adding Accessibility Attributes
-
-You can add custom attributes to objects, or even inject or hide
-objects from the UI hierarchy. It is simply a matter of
-overriding/implementing methods from the
-[NSAccessibility](http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/ApplicationKit/Protocols/NSAccessibility_Protocol/Reference/Reference.html)
-protocol where needed.
-
-You should peruse the {file:docs/AccessibilityTips.markdown Accessibility Tips}
-documentation before making nontrivial changes. There are a couple of
-guidelines you need to be aware of in order to make sure things remain
-compatible with AXElements.
-
-## Next Steps
-
-You may want to play with what you have learnt so far, see if you can
-find bugs and then fix them, or perhaps add missing features. ;)
-
-From here the next logical step would be to figure out how to trigger
-some sort of action and then inspect the UI for changes; for that
-topic you should read the {file:docs/Acting.markdown Acting Tutorial}.

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