| After months of putting it off, I finally glued my eyes open and waded through all the docs to figure out how to add AppleScript support to my Cocoa apps.
Complaints about the unhelpfulness of AppleScript dictionaries are, to put it politely, "not uncommon". Now, I start to see one possible reason. In the sdef(5) man page there is the diktat that:
Bear in mind that an sdef is intended to be a reference, not a tutorial. If you want to include any lengthy material, consider using a link to an external resource.
Personally, I don't see why an AppleScript dictionary can't be more ambitious, and as a end-user myself, that's certainly what I'd like to see more of in other developer's dictionaries. However, I'm relatively knew to this game (I didn't start scripting till a couple of years ago), and I'm not sure whether what I'm doing is still within a reasonable (albeit liberal) interpretation of that diktat or a gross offence to the restraint shown by other developers (who must surely have been tempted to do something similar), so I'd welcome responses from other AS users as to whether they'd find something like this acceptable.
So here's an example of my sdef as it appears in the Dictionary viewer; please note in particular the USAGE sample in the third item.
The link after each "HELP" _expression_ is a public link to a website that requires an internet connection, that my server's are not down at the time it's clicked, and general beneficence from the gods of all things to do with the chaos of internet connectivity. This is much of the explanation (in case someone thinks to ask), why just providing the links alone doesn't seem to me to be sufficient.
Anyway, this isn't in shipped code yet (determining whether I should ship something like this or not is the point of this post), so I welcome all comments, good/ bad / terrible idea etc.
properties ghostmode (boolean) : Is Ghost Mode on or off? transparency (boolean) : Is Transparency Mode on or off? logging (boolean) : Is App Logging on or off? ontop (boolean) : Is OSXClock always on top? alarmcounter (text, r/o) : If an alarm is set, how much time is left? the application's top-level scripting object. [see standard suite] elements properties name (text, r/o) : The name of the application. frontmost (boolean, r/o) : Is this the active application? version (text, r/o) : The version number of the application. responds to open, print, quit. ghost v : Toggle Ghost mode. USAGE: --toggle ghostmode's current state tell application "OSXClock" to ghost --turn Ghost mode on tell application "OSXClock" set x to ghostmode if x = false then ghost end tell HELP: Sqwarq Apps Scripting Examples
|