Getting Started with Shortcat

Last updated: July 15, 2013

Welcome to the Shortcat public beta! There are a few things that you need to know before you get started. You can find this page by going into the Shortcat preferences (Cmd+, while Shortcat is activated, or launching Shortcat when it’s already running), then clicking the Help pane. You can also view this in your browser of choice at http://shortcatapp.com/readme.html.

Changelog is viewable at http://shortcatapp.com/changelog.html.

Shortcat is in beta. Bugs are to be expected, and it may crash.

A Chinese version (中國版本) of this document can be found at http://kong.site44.com/shortcat_guide.html (thanks to Guoxiaosi.com).

TL;DR

It’s strongly recommended you read Usage to get the most out of Shortcat. Please read Compatibility before asking any questions about compatibility and Known Issues and Filing a bug before reporting bugs. Also be sure to check the Changelog for new features and changes!

  1. Cmd+Shift+Space to activate
  2. Enter a few letters of what you want to click. Examples:
  3. NEW To select an element, hold Control and type in the shortcut highlighted on the field.
  4. Enter to click.

Protips


Usage

Requirements

Activating Shortcat

The default activation shortcut is Command+Shift+Space. This brings up the Shortcat query window. You can change this shortcut in the Preferences. Preferences can be accessed via the menu icon or Cmd+, while Shortcat is active.

Querying

To query, simply type (in lowercase) a few letters of text from the element you would like to click on. These letters can be sequential or an abbreviation for the element.

For example, to click Desktop & Screen Saver in System Preferences, you can either type desk or dss.

Shortcat will highlight visible elements that match your query, with the green highlighted element being the top match.

If you want to click on an element that has no visible text, you can type . (period) and Shortcat will highlight all elements that it can detect and the corresponding shortcut for each element.

Element-type based matching

This feature is under development and will most likely change in the future.

You can search by element type (AKA AXRole): .button will show all buttons. It currently uses a different matching algorithm compared to the normal querying. Currently, you can’t combine a role search with a normal query, but this feature will be added in a later release.

A list of AXRoles can be found here.

Clicking

The top match in the green highlight will be clicked when you press Enter. You can use modifiers like Shift, Option, Command and Control while pressing Enter to click with the modifier. For example, Control+Enter becomes Control+Click, which is right click.

To click elements that are not the top match, simply hold Control and type in the letters displayed on the highlight.

To double-click an element, double tap Enter.

To mouse over the active element, tap Control.

To perform a click at the current cursor position, simply press Enter with no query. You can also double-click at the current cursor position by double-tapping Enter.

Scoping - Temporarily removed

This has been removed in v0.4.0. More thought is needed for this feature. It’ll come back.

Shortcat has the ability to scope your query to regions. Right now, regions are generally any area that is scrollable, so most lists and web views. To scope to a region, activate Shortcat, then hold `Shift`. This will highlight scopable regions. While holding `Shift`, press the corresponding key for the region you wish to scope. Shortcat will then update the blue focus ring, and your next query will only search within that region. **Example:** In Textual, searching everything can be slow. Activating Shortcat, then `Shift+A` will scope your query to the channel listing on the left.

Compatibility

Shortcat works with any application that properly exposes accessibility attributes. Standard OS X controls expose these attributes by default, so Shortcat works with most native applications on OS X. If applications implement custom controls (for animations, etc) and don’t implement accessibility attributes, Shortcat will not work for that application.

Below is a known list of applications classified by how well they work with Shortcat. If you find a popular application works particularly well, please let me know at http://support.shortcatapp.com

Compatible Applications

Semi-Compatible Applications

Incompatible Applications

Known Issues

Reporting bugs/feedback

Before you report a bug, please make sure you read the Known Issues above first, then the really important section below.

Bugs

Shortcat does not find an element

  1. Show all elements it recognises with .
  2. If nothing except the title bar is highlighted, it’s extremely likely the application does not expose accessibility attributes. You have to contact the author of the application and ask them to add accessibility attributes to their app.
  3. If you have the Accessibility Inspector tool (comes with Xcode), you can check by opening up the tool and hovering over the element. If it shows more detail than just the AXWindow, then file a bug report.

Filing a bug report

If Shortcat crashes, it should prompt you to send a crash report on the next launch. Please fill in the description field with what you did and steps to reproduce. If you put in your email, I will be able to contact you for further information and notify you of the status.

Please search for existing topics/reports before you create a new one. There’s a public Trello board at https://trello.com/board/shortcat-bugs/51ac6a3711f6b34606001d7f where there will be a list of issues that have been reported. If you have an account, you can comment and vote on issues.

The feedback site is at http://support.shortcatapp.com/.

Please include the following when you make a bug report:

Feedback

If you just wanna say how much you love Shortcat, tweet @shortcatapp! Otherwise, general feedback can be submitted at http://support.shortcatapp.com. If it’s a feature request, please hold off on it until it goes 1.0.0, because I have a massive feature roadmap as it is :)

Contact

Disclaimer

TL;DR: Shortcat is provided “as is”. Use at your own risk.

Shortcat is provided by Sproutcube “as is” and “with all faults.” Sproutcube makes no representations or warranties of any kind concerning the safety, suitability, lack of viruses, inaccuracies, typographical errors, or other harmful components of Shortcat. There are inherent dangers in the use of any software, and you are solely responsible for determining whether this Shortcat is compatible with your equipment and other software installed on your equipment. You are also solely responsible for the protection of your equipment and backup of your data, and Sproutcube will not be liable for any damages you may suffer in connection with using, modifying, or distributing Shortcat.