Myriad Helpers v2.0.2
Now compatible with OS X 10.11 El Capitan and later
What are they?
Myriad Helpers is a collection of Objective-C files that simplify some of the coding involved in AppleScriptObjC. It consists of a class, ObjectWithFords, that is designed to be used as a superclass for your AppleScript classes, and several categories that add new methods to a range of Cocoa classes, to make them easier to use from AppleScript.
What is a category?
In Objective-C, a category is a simple way of adding new methods to existing classes. Many of the methods added by the categories in this collection are designed to make it easier to use AppleScript’s aliases, files, and colon-delimted HFS paths with Cocoa classes, which normally deal only in POSIX paths and NSURLs.
What is ObjectWithFords for?
AppleScriptObjC is built on technology called the scripting bridge, which bridges between various AppleScript classes and Cocoa classes. This allows us, for example, to provide AppleScript text where NSStrings are required, and to coerce returned NSStrings to AppleScript text.
However, not all classes are bridged. For example, there is no bridging between AppleScript dates and Cocoa's NSDates — the two differ. ObjectWithFords has a catch-all method, ford:, that does these conversions intelligently for you. Pass it an AppleScript date and it will return the NSDate equivalent; pass it an NSDate and it will return the AppleScript equivalent. It will also convert aliases, files, data and NSURLs.
As well, it includes the fordDeep: method, which will perform the same conversions on lists and records and their elements, including those in any sublists and records.
If you find the idea of a catch-all method confusing, you can use any of the various dedicated conversion methods that ford: uses.
Is that all it does?
No. It has a method called fordDateString: that lets you easily create an AppleScript date from a string. Because of a bug in AppleScriptObjC, you cannot do this the normal AppleScript way (which has become pretty difficult in 10.6 anyway).
It has a method fordEvent that can be called repeatedly in time-consuming code to keep the UI of your app responsive.
It has a method theClass: that is a simpler and more obvious way of referring to a class.
And it provides a simple way of making instances of the classes that are bridged, rather than using long-winded calls like current application's NSString's stringWithString_.
Version 1.0.2 introduced a new method, fordTrig:, which gives you access to a range of trigonometry functions.
How do I install ObjectWithFords?
Add the two files, ObjectWithFords.h and ObjectWithFords.m, to your project. Then change the parent property of your script(s) from NSObject to ObjectWithFords. Your script will inherit the methods.
If you cannot use subclassing, you can use alloc and init to load an instance of the class, and call the methods on the instance.
Are there any gotchas with ObjectWithFords?
Obviously you have to watch out for name clashes — avoid names beginning with “ford” and you will be fine. Other than that, there are the usual issues of calling methods. For example, even though ford: will return an AppleScript date if pass an NSDate, you will still have to coerce the result using as date.
How do I use the categories?
Add the appropriate .h and .m files to your project, and call the methods as if they belonged to the relevant class.
What does NSDatePicker+MyriadHelpers do?
This is a category on the NSDatePicker class, adding two new methods:
dateAS returns the date displayed in the picker as an AppleScript date, and setDateAS: sets the picker’s date to an AppleScript date.
What does NSPathControl+MyriadHelpers do?
This is a category on the NSPathControl class, adding three new methods:
HFSFilepath returns a string containing the colon-delimited equivalent of the path displayed by the control. (If the control is showing a folder, it will append a colon to the end of the path.) setHFSFilepath: lets you pass the control a colon-delimited path for display. setPathAny: lets you pass an alias, file, colon-delimted path, NSURL or POSIX path for display.
What does NSAlert+MyriadHelpers do?
This is a category on NSAlert, and adds three methods to simplify showing both modal alerts and alerts as sheets. setMessage:buttons:text: lets you set the main properties of an alert. showModal shows an alert modally, and returns the name of the button pressed. showOver:telling:selector: shows an alert as a sheet, and when complete triggers the selector, passing the name of the button pressed.
What does NSOpenSave+MyriadHelpers do?
Lots of stuff. It gives you methods to set up open and save panels, and to show them modally and as sheets. In both cases, the result is a colon-delimited path, or if multiple selection is allowed, a list of paths (or NSURLs if you prefer). You can set the opening location with an alias, file, colon-delimited path, NSURL, or POSIX path.
What does NSWindow+MyriadHelpers do?
This is a category on NSWindow that has a method that makes it easier to show a window as a custom sheet.
What’s the big deal with sheets?
Because of a problem in AppleScriptObjC, you cannot display sheets without using some Objective-C code. You can do it with a protocol (which defines but does not implement methods) and, in the case of open and save panels, a deprecated method, but it is a fairly tedious affair. These categories aim to make the process a bit more AppleScript-like. Why do things the hard way?
When you say easier, can you give an example?
Sure. This is how you show a modal save panel normally:
set thePanel to current application's NSSavePanel's savePanel()
tell thePanel
setMessage_("Save the file")
setAllowedFileTypes_({"txt"})
setDirectoryURL_(POSIX path of (path to home folder))
setTitle_("My Save Title")
setNameFieldStringValue_("Some filename")
set returnCode to runModal()
end tell
set returnCode to returnCode as integer
if returnCode = (current application's NSFileHandlingPanelOKButton) as integer then
set theURL to thePanel's |URL|()
set POSIXPath to theURL's |path|()
log (((POSIXPath as text) as POSIX file) as text) -- HFS path
else
log "Cancel pressed"
end if
And this is how you would do the same thing with the relevant category file in your project:
tell current application's NSSavePanel to set thePanel to makeSaveAt_types_name_prompt_title_(path to home folder, {"txt"}, "Some filename", "Save the file", "My Save Title")
tell thePanel to set thePath to showModal()
if thePath = missing value then
log "Cancel pressed"
else
log thePath -- HFS path
end if
The simplification is greater for sheets.
But aren’t choose file, choose file name and choose folder easier still? Can’t I keep using them instead?
Yes they are, and yes you can. But the Cocoa versions give you extra control, the ablility to present as sheets, access to delegate methods, plus the ability to add an accessory view. If you don’t need any of these things, you might as well stick to the AppleScript panels.
Is there some dependency between the categories and the class?
No. You can add just the ObjectWithFords class, just one or more categories, or the lot.
So I can use these in my projects, free of charge?
That's the whole idea. Just remember that when you do, there are no guarantees or warranties whatsoever.
Is there any more documentation?
There's a ReadMe file. The individual methods are also documented in the .h files.
What’s with the Myriad Helpers project?
It’s just a sample project showing the methods in use. The various handlers are in different classes for the sake of clarity, not function. The category and ObjectWithFords files are in a folder called Helper Files, but they can be put pretty much anywhere you like.
What is the latest version?
Version 2.0.2. These files can be used in either garbage-collected projects or OS X 10.8-and-above apps that use Automatic Reference Counting.
Why ford?
When you come to a river and there is no bridge, sometimes the answer is to ford it.
