Mac developer looking for shortcut actions design advice

I’m want to add Shortcuts support to my document based Mac apps.

I already support AppleScript in my apps. Should I be thinking of Shortcuts as an AppleScript alternative … providing similar functionality? It looks that way to me, but I also see some pretty big areas of missing functionality and am wondering what to do about them.

In particular AppleScript’s standard dictionary provides standard ways to work with documents and windows across app. I don’t see that in Shortcuts. Does shortcuts have some way to work with documents and windows that I’m missing?

What sort of functionally do you need?

Looking at Apple’s document based apps such as Pages I see very little shortcuts support. Are there some good document based Mac apps that have more complete shortcuts support that you can recommend?

Ulysses
Craft
Drafts

1 Like

Thanks. Those apps all look to have nice shortcut support, but from what I can tell none of then are “documented based” in the traditional Cocoa developer use of the term.

I’m interested to see an app that supports opening specific files from different locations on your computer. Pages / Numbers / Keynote do this, but they all have very limited shortcut dictionaries.

I think you should absolutely add shortcuts support! In terms of what to add, you haven’t really explained what they do. But, as general advice I would consider any “verbs” a user can do in the app without UI as ripe for shortcuts use.

I.e. open, append, new, delete, find, import

1 Like

My apps are outline based, so the model will be rows, items, etc, but that’s not really what’s tripping me up right now. I think I can model that part OK.

The part that’s tripping me up is level of detail for document and window management. Just considering documents… with default AppleScript you can:

  • open existing documents
  • make new untitled documents
  • rename documents
  • close documents
  • save documents
  • print documents
  • find by name
  • find by modified

I can rebuild all that with actions, but it would be a lot of actions. I think it would require that I add a dedicated “DocumentEntity” to my Shortcuts support… all possible, but I don’t see other apps building at this level of detail… and I really don’t see any other “cocoa document based apps” supporting shortcut actions at all in a big way.

So I’m still looking for some existing document based apps so that I can figure out what the standard things to leave out are.

Shortcuts provides only a small fraction of the power of an AppleScript dictionary, but [in theory] without a high barrier to entry for ordinary end-users. Shortcuts is intentionally designed to be a limited solution for the vast majority of ordinary non-technical users; not a 100% solution for the 1% of (highly specialized) users, as traditional programming languages such as AppleScript and Swift are.

Shortcuts is designed to perform simple tasks, so that’s what you should design your app’s Shortcuts support to do.

Identify the smallest number of simple common repetitive operations which most of your users perform and expose those as Shortcuts commands, quick and simple to understand and use, nicely documented and easily dictated to Siri. That’s probably a good rule of thumb there: “What would I like to tell Siri to do for me?”

There is little point attempting to expose the same advanced level of functionality your app’s AS dictionary does: even if the Apple’s crude command-only app extensions+intents system could describe such capabilities, Shortcuts as it now exists—crude, clumsy, inexpressive—is really not fit to make best use of it. The harder a user pushes Shortcuts, the quicker she will tie herself in knots. It doesn’t scale up at all. Users who want greater granularity and total flexibility are best served by dropping into AppleScript to get it†, which they can do within Shortcuts via the “Run AppleScript” action.

TL;DR: Address the 1% of needs which the 99% of users have. Nail that and delight them.

† At least till Apple decides to drop the ax on AppleScript itself, but I guess we’ll all just deal with that when it happens.

1 Like

Thanks, this helps quite a bit.

I find that when scripting my apps many times using System Events to activate a menu item is a useful escape hatch … seems like that would fit into Shortcuts pretty well, but at the moment I’m not seeing a way to do that.

Is there a built in shortcut that can activate a menu item? Or do any existing apps have an action for that?

Under System Preferences - Keyboard - Shortcuts you can assign a keyboard shortcut to any menu item, either globally or per-application.

Then you can just use that one keystroke to activate the menu item.

1 Like

Thanks. I’m wondering if there’s a way to put that into a shortcuts app action. So that invoking the menu item is done automatically by the shortcut.

Bear in mind Shortcuts is designed first and foremost to serve iOS, which doesn’t really use menus.

Again, you can use the macOS-only “Run AppleScript” action to access System Events’s GUI Scripting suite, caveat standard security permissions.

1 Like

On iOS, document based apps and shortcuts I see:

  • 1Writer: New Document
  • Documents (Readdle): “dynamic action selection”, connect to computer, open recents, open favorites, search files, turn on/off vpn, open browser, play music
  • Editorial: run Editorial workflow
  • Files: get contents of folder, select file, delete file, move file, rename file and a lot more
  • Notes: not really document based, but a lot of actions worth considering
  • Textastic: Get File, Open File
1 Like

Better Touch Tool has a “Send Keyboard Shortcut” action that does just that. I use it to invoke menu commands in Microsoft Word.

2 Likes

I just download macOS 13 updates to Pages, Numbers, and Keynote to see the actions they recommend for document based apps… and nothing new from previous versions. Still just two actions to create document and open document. :frowning:

Coming back to this, I have added Shortcuts support to the latest preview version of Bike Outliner. I would love to get some feedback in this thread.