Applescript API documentation

Question

I want to make an AppleScript to automate the task of switching resolution on the MacBook Pro Retina.

Searching the internet for "applescript system preferences" I came across a page where some preferences are show. Being the scaled resolution thing new, it is not documented.

This brings to a bigger problem I have with AppleScript (mind that apart from copy-pasting something I never really programmed in it). Where is the documentation that tells me, for instance, tha the System Preferences object is actually called "System Preferences", that it has objects called "pane", that they have an id and that the expose id is "com.apple.preference.expose"?

It seems like there must be some sort of "secret" documentation for every program, and they must be huge, mapping all the object hierarchies and possible actions. In the end, AppleScript core is minimal and all you do is manipulate such programs. But where are they documented?

Answer 1

Ok this is how it works:

Where is the documentation that tells me, for instance, tha the System Preferences object is actually called "System Preferences"

The object is called "System Preferences" because that is the exact name of the application. What you're telling Applescript with this is I want to speak to the application named System Preferences (tell application "System Preferences" ...)

that it has objects called "pane"

Now it's the fun part. If you open your Library window (in Applescript Editor, Window > Library) you will see that there is a collection of scriptable applications available, the thing is that 'System Preferences' is not there. So let's find it: File > Open Dictionary > System Preferences. Now you got a window that both lets you drill down all available classes/commands/properties of the app and also a split window with relevant documentation (if you click on SSystem Preferences you'll see Cpane and by clicking on this you'll see Pid among others). The id of the pane for once more would be the name of the pane (lowercased and concatenated - I'm still looking into documentation for a strict definition on this). I hope that this will get you started.

---

S:Suite C:Class P:Property (the 'C' inside a circle stands for Command)

Answer 2

You're exactly right. Each program does have its own documentation for applescript. It's called its applescript dictionary. You can see the dictionary of any application by any of the following...

1) in AppleScript Editor, under the File menu, choose "Open Dictionary...". You can select an application from there and it will show its dictionary.

2) drag/drop an application onto the AppleScript Editor's icon.

3) there's a list of frequently-used dictionaries for fast access. Under the Window menu in AppleScript Editor choose "Library". You can double-click an application in that list. You can also modify that list to contain dictionaries that you want in the list.

Good luck.

Answer 3

You can ask AppleScript to tell you the ids for each of the panes.

tell application "System Preferences" to get the id of every pane

This is particuarly handy as it will tell you the ids for any third-party preference panes you have installed. For instance, I was able to work out that the pane for my Microsoft Natural keyboard is called com.microsoft.microsoftkeyboard

I haven't really explored this much yet, but I would expect that similar syntax exists to identify the objects within any scriptable application.