Applescript API documentation - macos

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.

Answer 4

I have another issue but you can have a look to my question as there is some hint in my script about your issue
HOW TO: display a check mark, disable a menu item, refresh a menubar
For instance:
tell application "System Preferences"
reveal anchor "displaysDisplayTab" of pane id "com.apple.preference.displays"
end tell
This code should directly put you in the resolution preferences of the system preference.
Then you can make a code to recuperate all the UI elements of the pane so that you now which action to trigger. Something like this should also work:
tell application "System Events"
tell application process "System Preferences"
set frontmost to true
delay 1
return every UI element of front window
return name of every UI element of front window
end tell
end tell
Hope it helps