Acorn Plugin Documentation

The different types of plugins

Acorn provides a simple Cocoa plugin API for you to alter the current bitmap layer, or perform actions with the current image.

You can write your plugins in either Objective-C or CocoaScript (which is a variant of JavaScript). Objective-C plugins are compiled and loaded up from bundles placed in the ~/Library/Application Support/Acorn/Plug-Ins/ folder. CocoaScript plugins are text files that end with .js . You can also view samples of the various types of plugins from the Acorn plugin GitHub repository: https://github.com/ccgus/AcornSDK

How plugins are loaded

At startup Acorn looks in the ~/Library/Application Support/Acorn/Plug-Ins/ folder for two types of files.

Objective-C bundles, ending with .acplugin. For example "Grayscale.acplugin". CocoaScript files, ending with .js .

The ObjC plugins must implement the ACPlugin protocol, and register themselves with Acorn to show up in a menu. (The ACPlugin protocol is defined in the file ACPlugin.h in the examples download). When the plugin is loaded up, you are given an opportunity to say "Hey, I want to go in the XYZ filter menu, and I want you to call this selector when I'm to be used". When your method is called, you are given a CIImage, you perform whatever you want to do to the image, and then you return a CIImage to be replace what you were given.

So for example, if I wanted to write a quick ObjC plugin to convert the layer to grayscale, my plugin would look something something like this:

@implementation ACGrayscalePlugin

+ (id) plugin {
    return [[[self alloc] init] autorelease];
}

- (void) willRegister:(id)pluginManager {

    [pluginManager addFilterMenuTitle:@"Grayscale"
                   withSuperMenuTitle:@"Color"
                               target:self
                               action:@selector(convertToGrayscale:userObject:)
                        keyEquivalent:@""
            keyEquivalentModifierMask:0
                           userObject:nil];

}

- (CIImage*) convertToGrayscale:(CIImage*)image userObject:(id)uo {
    CIFilter *[filter](filters.md) = [CIFilter filterWithName: @"CIColorMonochrome" keysAndValues: @"inputImage", image, nil];

    CIColor *color = [CIColor colorWithRed:0.5f green:0.5f blue:0.5f];

    [[filter](filters.md) setDefaults];
    [[filter](filters.md) setValue:color forKey:@"inputColor"];
    [[filter](filters.md) setValue:[NSNumber numberWithFloat:1] forKey:@"inputIntensity"];

    return [[filter](filters.md) valueForKey: @"outputImage"];
}

@end

If you don't want to return an image because you have got something else you want to do, just return nil.

You can also get a reference to the calling image by asking the document controller what the current document is: [[NSDocumentController sharedDocumentController] currentDocument].

This returns a subclass of NSDocument (ACDocument), and you can use the various methods that NSDocument provides to find out information about the image. In addition, you can get different representations of the image as NSData like so:

NSDocument *theDoc = [[NSDocumentController sharedDocumentController] currentDocument];
NSData *tiffData = [theDoc dataRepresentationOfType:@"public.tiff"];

Other UTIs you can use: public.png, public.jpeg, public.tiff, com.compuserve.gif, com.microsoft.bmp, com.apple.icns, and com.adobe.pdf

CocoaScript and JavaScript Plugins CocoaScript plugins work a lot like the Objective-C plugins, only they are a lot easier to write since you just put a text file ending with .js in the Plug-Ins folder. You can see sample CocoaScript plugins on the GitHub repository: https://github.com/ccgus/AcornSDK/tree/master/jstalk

Another big advantage of writing a plugin in CocoaScript, is that you do not need to stop and restart Acorn to modify an already loaded plugin. Just edit the file, and rerun it from Acorn.

• ACScriptSuperMenuTitle, The supermenu that the plugin should show up in.
• ACScriptMenuTitle, The title of the plugin
• ACShortcutKey, the shortcut key (a string)
• ACShortcutMask, the name of the modifier(s) needed to invoke the plugin (control, option, command shift)

Acorn Additions Here are some various additions to Objective-C (and also useable from the CocoaScript side) that Acorn provides:

Additions to NSImage:
- (CIImage *)CIImage;

Additions to CIImage:
- (NSImage *)NSImage; - (NSImage *)NSImageFromRect:(CGRect)r;

Additions to NSDocumentController:
- (id)newDocumentWithImageData:(NSData*)data; /* takes bitmap data, (PNG, TIFF) */

---