Acorn Acorn 4

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, JSTalk (which is a variant of JavaScript) or Python. Objective-C plugins are compiled and loaded up from bundles placed in the ~/Library/Application Support/Acorn/Plug-Ins/ folder. JSTalk plugins are text files that end with .jstalk, and Python plugins are text files ending with .py. 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".

JSTalk files, ending with .jstalk.

Python files, ending with .py. For example "Grayscale.py"


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 = [CIFilter filterWithName: @"CIColorMonochrome" keysAndValues: @"inputImage", image, nil];

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

[filter setDefaults];

[filter setValue:color forKey:@"inputColor"];

[filter setValue:[NSNumber numberWithFloat:1] forKey:@"inputIntensity"];

return [filter 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



JSTalk and JavaScript Plugins

JSTalk 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 .jstalk in the Plug-Ins folder.  You can see sample JSTalk plugins on the GitHub repository: https://github.com/ccgus/AcornSDK/tree/master/jstalk


Another big advantage of writing a plugin in JSTalk, 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 JSTalk 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) */