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?

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 thenlog "Cancel pressed"elselog 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.

EVERYDAY APPLESCRIPTObjC

Everyday AppleScriptObjC, Third Edition by Shane Stanley is the perfect introduction to AppleScriptObjC scripting in Mavericks and later. This new edition covers the changes introduced in El Capitan, and contains several new chapters.

Learn how to use AppleScriptObjC directly in your scripts in El Capitan and Yosemite

Learn how to write and deploy AppleScriptObjC-based script libraries in Mavericks and later

Full of useful snippets of code

Explains how to make sense of the Cocoa documentation

Covers the main classes useful to scripters

BRIDGEPLUS LIBRARY

BridgePlus is a free script library for use under OS X 10.9 and later, designed to improve and simplify the use of AppleScriptObjC. Read more and download it here: BridgePlus Script Library.

ABOUT THE AUTHOR

Shane Stanley (center, in white) is a long-time AppleScript user and trainer from Melbourne, Australia. He co-presented the AppleScript Pro Sessions training events in the US for 10 years, and specializes in automating workflows in the publishing industry. (photo by Björn Zitting)

VIDEO: ACTIONS AND OULETS

A video demonstrating the connection of application interface elements to their corresponding AppleScript function code using Interface Builder outlets and actions. More here.