There’s a subversion repository as well if you’re keen to stay up to date.

The GetCurrentEventKeyModifiers() call works on Mac OS X v10.2 and later through which one can check for shiftKey, cmdKey, optionKey and controlKey.

I use the something like the following to check if the shift key is pressed during launch for my compression app.

#import <Cocoa/Cocoa.h>
#import <Carbon/Carbon.h>

int main(int argc, char *argv[]) {
    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
    if((GetCurrentEventKeyModifiers() & shiftKey)!=0) {
        // Change something useful
        NSLog(@"Shift key pressed during launch");
    }
    [[NSApplication sharedApplication] run];
    [pool release];
    return 0;
}

In the highly unlikely event that you’ve just got a call to NSApplicationMain in your main function (joking), you can just test (GetCurrentEventKeyModifiers() & shiftKey)!=0 in the -applicationWillFinishLaunching: method in your NSApplication delegate.

Any new APIs in Leopard to achieve this or any easier way?

CTGradient contains an incredible diversity of built-in gradients, gradient styles, and methods for creating fancy rainbows, radial gradients, linear gradients, aqua gradients, and a number of other interesting class and instance methods. It allows you to dynamically alter gradients by adding or removing colors, changing the level of transparency, filling NSRects or NSBezierPaths, rotating the gradient, etc. For demonstration purposes, all these features are excellent. For production, this is a nightmare.

CTGradient.m weighs in at over 1300 lines of code.

Ignoring Mr. Weider’s unique style of formatting, take a look through the code. If you’re putting this class in an application, you can immediately remove over a thousand lines. Just like that. But if you take some time to understand what’s going on, you can optimize this thing till it runs like a Ferrari.

You’ll notice Trimmit uses a gradient background for it’s window. Let’s cut down CTGradient until it matches the level of optimization of Trimmit’s gradient code.

Clear the junk

Firstly, let’s remove the methods we know for sure we won’t need. Remove the following methods completely from both the interface and the implementation (scroll down for more):

// We don't need the preset gradients

+ (id)dividerGradient;
+ (id)statusBarGradient;
+ (id)aquaSelectedGradient;
+ (id)aquaNormalGradient;
+ (id)aquaPressedGradient;
+ (id)unifiedSelectedGradient;
+ (id)unifiedNormalGradient;
+ (id)unifiedPressedGradient;
+ (id)unifiedDarkGradient;
+ (id)sourceListSelectedGradient;
+ (id)sourceListUnselectedGradient;
+ (id)rainbowGradient;
+ (id)hydrogenSpectrumGradient;

// We won't make any drastic modifications to the gradient once created

- (CTGradient *)gradientWithAlphaComponent:(float)alpha;
- (CTGradient *)addColorStop:(NSColor *)color atPosition:(float)position;
- (CTGradient *)removeColorStopAtIndex:(unsigned)index;
- (CTGradient *)removeColorStopAtPosition:(float)position;
- (CTGradientBlendingMode)blendingMode;
- (NSColor *)colorStopAtIndex:(unsigned)index;
- (NSColor *)colorAtPosition:(float)position;

// Now we don't need to conform to the NSCopying and NSCoding protocols

- (id)copyWithZone:(NSZone *)zone;
- (void)encodeWithCoder:(NSCoder *)coder;
- (id)initWithCoder:(NSCoder *)coder;

// We only need to fill a simple NSRect

- (void)drawSwatchInRect:(NSRect)rect;
- (void)radialFillRect:(NSRect)rect;
- (void)fillBezierPath:(NSBezierPath *)path angle:(float)angle;
- (void)radialFillBezierPath:(NSBezierPath *)path;

// Remove the entire (Private) category;
// but leave -addElement:

- (void)_commonInit;
// move setBlendingMode code into init
- (void)setBlendingMode:(CTGradientBlendingMode)mode;
- (CTGradientElement *)elementAtIndex:(unsigned)index;
- (CTGradientElement)removeElementAtIndex:(unsigned)index;
- (CTGradientElement)removeElementAtPosition:(float)position;

The following C functions are now unused:

static void chromaticEvaluation(void *info, const float *in, float *out);
static void inverseChromaticEvaluation(void *info, const float *in, float *out);
static void transformRGB_HSV(float *components);
static void transformHSV_RGB(float *components);
static void resolveHSV(float *color1, float *color2);

And also remove the following from the header:

typedef enum  _CTBlendingMode
    {
    CTLinearBlendingMode,
    CTChromaticBlendingMode,
    CTInverseChromaticBlendingMode
    } CTGradientBlendingMode;

Remove the <protocols> and unnecessary instance variables so the interface looks like this:

@interface CTGradient : NSObject {
    CTGradientElement* elementList;
    CGFunctionRef gradientFunction;
}
+ (id)gradientWithBeginningColor:(NSColor *)begin endingColor:(NSColor *)end;
- (void)fillRect:(NSRect)rect angle:(float)angle;
- (void)addElement:(CTGradientElement *)newElement;
@end

Before we go further, we’ll need to take a detour and fix the remaining code so that it compiles. That’s easy enough - just remove any references to code we’ve removed.

If you’ve been following along, your CTGradient should now look like this (also made it readable!).

In a few short minutes, we’re down from more than 1300 to a little over 200 lines.

It gets better.

Optimize it

First stop, fillRect:angle:. Since the gradient for Trimmit’s window only runs vertically (angle 90), we can straight away take out the angle argument, and also cut the entire if / else structure with the angle down to the two lines that are under the if(angle == 90). Ah, much better.

Now things start getting a teeny bit more complex - and fun.

The CTGradient code is written so that one can have many different color stops. The CTGradientElement struct has a nextElement which points to the next CTGradientElement and the position of the current element is stored under the float position. However, we need just two - the starting and ending shades.

Let’s take a look at cutting the multiple elements down to just two.

The addElement: method has a lot of looping to insert the element at the correct place. However, since we know that we only ever need two, we can cut it down to this:

- (void)addElement:(CTGradientElement *)newElement {
    if(elementList) {
        // elementList exists, add second element
        elementList->nextElement = malloc(sizeof(CTGradientElement));
        *(elementList->nextElement) = *newElement;
        elementList->nextElement->nextElement = 0;
    } else {
        // no elements - add first element
        elementList = malloc(sizeof(CTGradientElement));
        *elementList = *newElement;
        elementList->nextElement = 0;
    }
}

Similarly with dealloc,

- (void)dealloc {
    CGFunctionRelease(gradientFunction);
    free(elementList->nextElement);
    free(elementList);
    [super dealloc];
}

While we’re at it, let’s clean up init as well:

- (id)init {
    if(self = [super init]) {
        CGFunctionCallbacks evaluationCallbackInfo = {0 , &linearEvaluation, 0};
        static const float input_value_range[2] = { 0, 1 };
        static const float output_value_ranges[8] = { 0, 1, 0, 1, 0, 1, 0, 1 };
        gradientFunction = CGFunctionCreate(&elementList, 1, input_value_range, 4, output_value_ranges, &evaluationCallbackInfo);
    }
    return self;
}

Now we head to the linearEvaluation function. info passed in refers to elementList (see the CGFunctionCreate call). Again, since we know that we’ll only ever have two elements we can reduce it to:

void linearEvaluation (void *info, const float *in, float *out) {
    float position = *in;

    CTGradientElement *color1 = *(CTGradientElement **)info;
    CTGradientElement *color2 = color1->nextElement;

    out[0] = (color2->red - color1->red)*position + color1->red; 
    out[1] = (color2->green - color1->green)*position + color1->green;
    out[2] = (color2->blue - color1->blue)*position + color1->blue;
    out[3] = (color2->alpha - color1->alpha)*position + color1->alpha;
}

And now we can finally remove the lines from +gradientWithBeginningColor:endingColor: where the positions are set, and also remove the position float from the CTGradientElement struct.

We’re now down to a little over 100 lines. Your CTGradientElement.m should now be looking something like this. Going well, but let’s take things up a notch.

For Trimmit’s background, we’re not interested in the red, green, blue and alpha components - we just need a grayscale shading. This is the most fun part.

Instead of float red, green, blue, alpha; in the CTGradientElement struct, we can have just float shade;.

Now, during init we have:

CGFunctionCallbacks evaluationCallbackInfo = {0 , &linearEvaluation, 0};
static const float input_value_range[2] = { 0, 1 };
static const float output_value_ranges[8] = { 0, 1, 0, 1, 0, 1, 0, 1 };
gradientFunction = CGFunctionCreate(&elementList, 1, input_value_range, 4, output_value_ranges, &evaluationCallbackInfo);

The third argument, input_value_range is the domain. This gets passed into linearEvalution through *in.This is the independent variable. When we’re drawing the gradient, linearEvaluation is called with *in (the domain) starting at the first value of input_value_range and ending up at the second. So, something like 0.000, 0.001, 0.002 … 0.998, 0.999, 1.000. The function’s job is to set the the color components for each given value of the domain.

The first optimization we can make here is to return only one channel instead of four. This changes it to:

- (id)init {
    if (self = [super init]) {
        CGFunctionCallbacks evaluationCallbackInfo = {0, &linearEvaluation, 0};
        static const float range[2] = {0, 1};
        static const float domain[2] = {0, 1};
        gradientFunction = CGFunctionCreate(&elementList, 1, domain, 1, range, &evaluationCallbackInfo);
    }
    return self;
}

This change impacts back on the linearEvaluation function - now it only needs to return one channel:

void linearEvaluation (void *info, const float *in, float *out) {
    CTGradientElement *color1 = *(CTGradientElement **)info;
    out[0] = (color1->nextElement->shade - color1->shade)*(*in) + color1->shade;
}

And don’t forget +gradientWithBeginningColor:endingColor:. We improve performance here, as we only need the shade - not a color. We can rename it to something appropriate.

+ (id)gradientWithBeginningShade:(float)begin endingShade:(float)end {
    id newInstance = [[[self class] alloc] init];
    CTGradientElement color1, color2;

    color1.shade = begin; color2.shade = end;

    [newInstance addElement:&color1];
    [newInstance addElement:&color2];
    return [newInstance autorelease];
}

Now we’re only returning one grayscale channel. But hold on, we’re still in the RGB colorspace! That’s easily fixed. In fillRect:, replace:

#if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_4
    CGColorSpaceRef colorspace = CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB);
#else
    CGColorSpaceRef colorspace = CGColorSpaceCreateDeviceRGB();
#endif

with:

CGColorSpaceRef colorspace = CGColorSpaceCreateDeviceGray();

CGColorSpaceCreateDeviceGray is device-dependent on Mac OS X 10.3 and below, but starting from Tiger, it’s now device-independent which is good in terms of appearance.

While we’re in fillRect:, we can also make a few more improvements:

- (void)fillRect:(NSRect)rect {
    CGContextRef currentContext = [[NSGraphicsContext currentContext] graphicsPort];
    CGContextSaveGState(currentContext);
    CGColorSpaceRef colorspace = CGColorSpaceCreateDeviceGray();
    CGContextClipToRect(currentContext, *(CGRect *)&rect);
    CGShadingRef myCGShading = CGShadingCreateAxial(colorspace, CGPointMake(0, 0), CGPointMake(0, NSMaxY(rect)), gradientFunction, 0, 0);
    CGContextDrawShading(currentContext, myCGShading);

    CGShadingRelease(myCGShading);
    CGColorSpaceRelease(colorspace);
    CGContextRestoreGState(currentContext);
}

I moved the startPoint and endPoint CGPoints straight into the CGShadingCreateAxial call. Also, we only ever fill the whole view with the gradient, so just put in 0 instead of using NSMinX and NSMinY. We could replace the CGPointMake(0, 0) with (CGPoint){0,0}, but I’m not sure if that’d be noticeably faster.

Our code is at a lean 80 lines. Now for the biggest change yet.

Heading back to dear old linearEvaluation. Look at this line:

out[0] = (color1->nextElement->shade - color1->shade)*(*in) + color1->shade;

What’s happening here? Think about it like this:

Essentially, we’re just "graphing" a straight line:

y = mx + c

where x is the position, *in, and y is the shade we return (out[0]), and c is the initial shade.

Since our x value only goes from 0 to 1 (see domain in CGFunctionCreate), at x = 0, we will have y = c. At x = 1, we’ll have y = m + c.

So we only need the start shade as our *info value, since we can have m as the difference between the final and initial shades. Let’s effect this in our code.

We can get rid of the CTGradientElement struct. Remove from the header:

typedef struct _CTGradientElement {
    float shade;
    struct _CTGradientElement *nextElement;
} CTGradientElement;

Instead of the struct, we’ll use a single shade instance variable. We don’t need the +gradientWithBeginningShade:endingShade: anymore, nor do we need -addElement:. So our interface now looks like this:

@interface CTGradient : NSObject {
    float shade;
    CGFunctionRef gradientFunction;
}
- (void)fillRect:(NSRect)rect;
@end

From the implementation, we can remove the free calls in dealloc as well as the whole of +gradientWithBeginningShade:endingShade: and addElement:. We can set the shade in the init method (and replace &elementList with &shade), and change the linearEvaluation function to:

void linearEvaluation (void *info, const float *in, float *out) {
    out[0] = *(float*)info + (*in)*0.1;
}

The 0.1 is what determines how much brighter the top of the gradient is (it’s the m value of our straight line) compared to the bottom.

But since the (*in)*0.1 will go from 0 to 0.1 (as *in goes from 0 to 1), we can actually change the domain we declare for CGFunctionCreate to {0, 0.1} and have our function as:

void linearEvaluation (void *info, const float *in, float *out) {
    out[0] = *(float*)info + *in;
}

You can now add accessors for shade if you need to change the shade of the gradient or you could even have an initWithShade: method. In fact, here’s an Xcode project with the gradient.

Lean Gradient Xcode Project

We now have our gradient code down from 1300 lines to just over 30 lines.

We’ve almost reached a similar level of optimization to Trimmit’s gradient. There will be further optimizations you can make, but it depends on what you’re using the gradient for. For example, if the gradient you’re drawing is always the same, you can optimize further by removing the shade instance variable and all references to it, and hardcode the value into the linearEvaluation function.

Getting to the end of this article, you’re probably thinking that it would be a bit of a waste to use CTGradient if by the time you optimize it for your application, it doesn’t resemble the original at all. And you’re quite right. The documentation already shows you how to draw gradients, yet the number of applications using CTGradient - the whole 1300 lines of it - is astonishing.

Please: When you use other people’s code, don’t put it in without a thought. Go through it, understand it, and optimize it for your specific need. For the better performance and reduced RAM usage, computers will thank you.

Finder info, .DS_Store files, resource forks, debug symbols… They do nothing for the user short of wasting disk space. For the developer, extra bandwidth costs. Do people not realise this is a problem, or are they just too lazy to act? Either way, the solution is simple.

You can clean apps (sometimes to less than half their original size) with some basic commands in the Terminal. But this takes time, and what’s more, Mac users in general have an aversion to the command line. Enter Trimmit.

Trimmit is a svelte utility which takes the pain out of keeping your applications as tight as possible. I use it on Flow each time I seed a build, and I seriously doubt the process could any easier.

Brian Amerige

Trimmit uses superfast UNIX APIs, Apple’s own developer tools, and the rock-solid Cocoa framework to automate your cleaning process. Just drop your built app onto it, maybe configure a few settings, and you’re away. It doesn’t get any easier - or faster.

Other applications claim to save disk space by stripping universal binaries, or removing languages. Trimmit does all of that - and more. But it works. Look at this screenshot from Xslimmer regarding Xcode:

Xslimmer naively believes that only two architectures can exist in any application, but the truth is revealed by Trimmit:

Because Trimmit interacts with the shell (zsh, in fact), no similar application can even come close to it’s level of power, accuracy and performance.

The results speak for themselves.

Use Trimmit to recover disk space that third-party applications so rudely waste.

Go get Trimmit.

Java, Python and Ruby can access Cocoa APIs and Objective-C classes. What about the super-extensible yet severely under-appreciated Javascript? With the WebKit framework, you can access Objective-C from any script present in a HTML document.

A `WebScriptObject` is an Objective-C wrapper passed to your application from the scripting environment. You can’t create an instance directly, but you need to get a `WebScriptObject` by sending `webScriptObject` to a WebView.

Paraphrase of WebScriptObject Overview

This class, WebScriptObject, lets you “talk” and “listen” to Javascript (or any other code allowable inside HTML <script> tags). That is, you can run Javascript code or functions in the WebView, but you can also let the Javascript run Objective-C methods.

This is the same way Dashboard widgets interact with Cocoa plugins. You know how you access window.widget in your Javascript? That’s an Objective-C class you’re referencing. The WebKit framework provides all the necessary classes and functionality for this interaction, making this seemingly difficult task ridiculously easy.

Exposing an Objective-C class to the scripting environment

Exposing a class to the scripting environment is very easy. You can use key-value coding methods (for example, setValue:forKey: and valueForKey:) to get and set the properties of a WebScriptObject. These will be accessible as children of the window object in Javascript. Use the removeWebScriptKey: method to remove a scripting object property.

As an example, let’s say we have a class NSFoo. We’ve linked to the WebKit framework and webView is a WebView.

We use the delegate method webView:windowScriptObjectAvailable: to ensure that the WebScriptObject is available before we start using it. Then we expose an instance of NSFoo to the scripting environment:

- (void)webView:(WebView *)sender windowScriptObjectAvailable: (WebScriptObject *)windowScriptObject {
    NSFoo *myFoo = [[NSFoo alloc] init];

    scriptObject = windowScriptObject;
    [scriptObject setValue:myFoo forKey:@"foo"];
}

Now you can access foo through javascript;

<script language='text/javascript'>
var myFoo = foo;
</script>

Allow Javascript access

For obvious security reasons, no methods or KVC keys are exposed to the Javascript environment by default. This means at this stage while window.foo exists, you can’t do much with it. To allow Javascript to send messages or get / set properties, the following two class methods need to be utilized:

+ (BOOL)isSelectorExcludedFromWebScript:(SEL)aSelector;
+ (BOOL)isKeyExcludedFromWebScript:(const char *)name;

So for example, if we want to allow Javascript to send a bar: message to a class, all we have to do is add the following class method to the implementation:

+ (BOOL)isSelectorExcludedFromWebScript:(SEL)selector {
    if ( selector == @selector(bar:) ) {
        return NO;
    }
    return YES;
}

Now running foo.bar_(0) in Javascript will be equivalent to running [myFoo bar:0] in Objective-C. Why the underscore? Selectors accessed from Javascript are renamed using the following rules:

• Any colon (":") in the Objective-C selector is replaced by an underscore ("_").
• Any underscore in the Objective-C selector is prefixed with a dollar sign ("$").
• Any dollar sign in the Objective-C selector is prefixed with another dollar sign.

So a method called doAction:(id)action withThing:(id)thing will be turned into doAction_withThing_(action,thing), while do$This: will become do$$This_. This is often pretty ugly and inconvenient. Fortunately, the Javascript name for the selectors can be changed.

Change Javascript selector names

Using + (NSString *)webScriptNameForSelector:(SEL)sel, we can change the name of the selector in Javascript:

+ (NSString *)webScriptNameForSelector:(SEL)sel
{
    if (sel == @selector(bar:))
        return @"bar";
    return nil;
}

Now we can run foo.bar(0) in Javascript to equal [myFoo bar:0]. Here are a few more examples:

+ (NSString *)webScriptNameForSelector:(SEL)sel
{
    if (sel == @selector(performTransition))
        return @"performTransition";    // widget.performTransition()
    else if (sel == @selector(prepareForTransition:))
        return @"prepareForTransition"; // widget.prepareForTransition(arg)
    else if (sel == @selector(setPreference:forKey:))
        return @"setPreferenceForKey";  // widget.setPreferenceForKey(pref,key)
    else if (sel == @selector(preferenceForKey:))
        return @"preferenceForKey";     // widget.preferenceForKey(key)
    return nil;
}

If you want to expose all the instance methods of the class to the scripting environment, just return NO without doing any checks:

+ (BOOL)isSelectorExcludedFromWebScript:(SEL)selector { return NO; }

Remember: selectors are converted into Javascript functions, so even if the method doesn’t need any arguments, you still need to add the parenthesis at the end for the Javascript; eg. [object doMethod] becomes object.doMethod().

Key-Value-Coding from Javascript

Exposing KVC keys is a similar procedure. Here we’re giving access to the “name” property:

+ (BOOL)isKeyExcludedFromWebScript:(const char *)property {
    if (strcmp(property, "name") == 0) {
        return NO;
    }
    return YES;
}

Now in Javascript, we can read and write foo.name. Reading foo.name will be equivalent to [myFoo name] and writing to it (foo.name = "A big foo") will be the same as running [myFoo setName:@"A big foo"].

As before, just return NO without any checks to allow all KVC keys to be accessed from the scripting environment.

Summary

• Load WebKit.framework which contains the classes WebView and WebScriptObject.
• Send setValue:forKey: to a WebScriptObject; makes an object available to the scripting environment.
• Implement +isSelectorExcludedFromWebScript: and +isKeyExcludedFromWebScript: and return NO to allow the scripting environment to run a method or access a key.
• Use webScriptNameForSelector: / webScriptNameForKey: to specify the names of your methods / keys as seen by Javascript.

Further reading

• WebKit Documentation
• WebScripting Documentation
• Obj-C From JavaScript
• TurtleScript

It uses Core Graphics and Core Image APIs for the transition effects to animate the window / view, which probably needs a minimum of Mac OS X Tiger. The full source code is available.

MagicHat is a programmer’s research and reference tool. With MagicHat, you navigate through Cocoa’s application programming interface (API); review the declarations of language elements such as methods, functions, and constants; and retrieve relevant passages from the Cocoa developer documentation. MagicHat helps you unravel unfamiliar code, whether building blocks from the Cocoa software kits, programming examples, or programs written by your own development team.

MagicHat lets you look at the declarations of public, private and local (installed) frameworks. This is a good graphical way to look at the structure of a framework, but is limited to Objective-C; which shouldn’t matter much for general use.

Above: MagicHat in action, displaying Disco.app’s Smoke.framework

Class-Dump

Class-Dump is one of the easiest to use command line utilities to look at the Objective-C portions of Mach-O files. The command is immediately available after moving the downloaded file to /usr/bin/ (you may need to use sudo mv). Executing it involves a running a simple “class-dump nameoffile” command in Terminal and the output is a nicely formatted Objective-C header. Objective-C output is the feature that makes this tool unique. It is especially useful if you need header files for frameworks which don’t include them, but it also gives you an idea as to the classes and methods present in the framework.

otool

otool provides one of the most comprehensive feature-sets - its primary role being to display parts of object files or libraries. You’ll generally find that using otool gives you access to frameworks such as CoreGraphics, which don’t contain Objective-C classes. The -v command will give you verbose output; -o displays the Objective-C and -t the text sections.

Take ‘em apart

Using these tools, you are now equipped to examine in detail most frameworks and libraries. Be aware that searching though and discovering new functions takes a lot of experimentation and trial and error - which the primary reason I leave it to people like Wade Tregaskis (who, like me, lives in Melbourne. Never met him, though).

Obligatory disclaimer: The private frameworks are probably private for a reason. Meddle with them at your own risk.

(For those adventurous souls, the Core Graphics framework is located at /System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/CoreGraphics.framework but there are plenty of other private frameworks besides this one; Core Graphics just happens to have the window transition effects.

Ok, did this help, and what did I miss?

The function CGSSetWindowWarp is part of the private portion of Core Graphics. Although its just as obscure and undocumented as the rest of the private parts of the framework, there has been some discovery and progress into its usage. Erling Ellingsen has written (a while ago) about CGSSetWindowWarp on his blog, and he also shows some very interesting screenshots of what’s possible.

So, how do you use this incredible function in your Cocoa (or Carbon) application?

CGSSetWindowWarp Usage

Including the header

Whenever you use private Core Graphics functions, you generally need to #import either one of CoreGraphicsServices.h or CGSPrivate.h (available for download with my Core Graphics ebook). However, if you’re not interested in using the rest of the Core Graphics API, you can get away with simply adding the following to your main class’ header file:

typedef struct CGPointWarp {
        CGPoint local;
        CGPoint global;
}CGPointWarp;

typedef int CGSConnectionID;
typedef int CGSWindowID;

extern CGSConnectionID _CGSDefaultConnection();

extern CGError CGSSetWindowWarp(CGSConnectionID, CGSWindowID, int w, int h, CGPointWarp mesh[w][h]);
extern OSStatus CGSGetScreenRectForWindow(CGSConnectionID cid, CGSWindowID wid, CGRect *outRect);
extern OSStatus CGSGetWindowBounds(CGSConnectionID cid, CGSWindowID wid, CGRect *bounds);

As you’ve probably guessed, the function that actually applies the mesh transform is CGSSetWindowWarp. You can create a mesh in two different ways.

Creating the mesh

To create a mesh, we need to specify how many points we’re going to take for our grid length-wise and width-wise. Something like this:

#define H 64
#define W 5

We’ll also need to refer to the position and size of the frame so the following code in the method you’re writing this will give us access to the frame of the NSWindow:

CGRect frame;
CGSGetWindowBounds(cid, [window windowNumber], &frame);

The use of CGSGetWindowBounds ensures we get the apparent frame rather than just the frame computed by our code as we’ll be applying various transformations.

The first way to create a mesh requires more labor (yes, its tiring to code) but gives you greater control over the mesh and the transformations applied to the NSWindow.

Manual mesh

CGPointWarp meshes[H][W] =
{
{ {{0, 0},{10, 10}}, {{200,0},{180,12}} },
{ {{0, 50},{0,50}}, {{200,50},{200,50}} },
{ {{0,100},{0,100}}, {{200,100},{200,100}} },
{ {{0,150},{0,150}}, {{200,150},{200,150}} },
{ {{0,200},{0,200}}, {{200,200},{200,200}} },
};

Here, you specify firstly the coordinates of the point which you’re taking, and where you want to move that point. The first line in the above code takes (0,0) and moves it to (10,10) and moves (200,0) to (180,12). However, the first set of coordinates are local coordinates, and the second set are global. (ie., the first set are on the plane of the window, while the second set use the screen as the plane. This is to allow the window to be stretched out beyond the scope of the current frame.) We could solve this issue by using:

int x = frame.origin.x;
int y = frame.origin.y;
CGPointWarp meshes2[H][W] =
{
{ {{0, 0},{x, y}}, {{200,0},{x+200,y}} },
{ {{0, 50},{x,y+50}}, {{200,50},{x+200,y+50}} },
{ {{0,100},{x,y+100}}, {{200,100},{x+200,y+100}} },
{ {{0,150},{x,y+150}}, {{200,150},{x+200,y+150}} },
{ {{0,200},{x,y+200}}, {{200,200},{x+200,y+200}} },
};

The preceding code just warps the window of size 200×200 to its current position so no change is observable. If we wanted to stretch out the middle of the window horizontally, we could use a mesh in the form:

int x = frame.origin.x;
int y = frame.origin.y;
CGPointWarp stretchThroughMiddleMesh[H][W] =
{
{ {{0, 0},{x, y}}, {{200,0},{x+200,y}} },
{ {{0, 50},{x-10,y+50}}, {{200,50},{x+200+10,y+50}} },
{ {{0,100},{x-20,y+100}}, {{200,100},{x+200+20,y+100}} },
{ {{0,150},{x-10,y+150}}, {{200,150},{x+200+10,y+150}} },
{ {{0,200},{x,y+200}}, {{200,200},{x+200+10,y+200}} },
};

We’ve taken the side where x=0 and moved x further back along the middle, and done the opposite on the opposite side (where x=200). This results in the NSWindow being warped to have a bulge in the middle.

Again, this would only look like the screenshot on a window with a height and width of 200. For a window that’s a different size, you’ll need to change the values to match the height and width of the window. For the y-values in the mesh (x, x+50, x+100, etc. in the different rows), the numbers are determined by how many points you’ve taken (your value for H) and the width of the window. The general formula you would use would be x + ( frame.size.height / (W-1) ). You’ll see this more clearly in the second method.

Mesh through iterative formulae

The second method to create a mesh is to run a loop to configure your individual points. Here’s a basic example that creates a mesh that would be identical to the current state of the window:

int h;
int w;
CGPointWarp meshes[H][W];
for (h = 0; h < H; h++) {
    for (w = 0; w < W; w++) {
        CGPointWarp point;
        point.local.x = w * (frame.size.width / (W - 1));
        point.local.y = h * (frame.size.height / (H - 1));
        point.global.x = point.local.x + frame.origin.x;
        point.global.y = point.local.y + frame.origin.y;

        meshes[h][w] = point;
    }
}

Obviously we want to transform the window somehow. We need to apply some sort of mathematical function to the points to make them deviate from their original positions or coordinates. (This is the part where you start to wish you’d paid more attention in math class).

Lets say we want to skew the window using the x-axis. Each successive x-value needs to be greater than the previous one. Since we’re looping through each point, at any time in the inner for loop, the values of the current point are (w,h). (In Cartesian coordinates the x value is first, followed by the y value) In order to increase each successive value for x, we need to add something. But, we need to add more than what we did the previous time. The easiest way to do this without adding any new variables is to use the value that we’re incrementing each time - the x value itself. So, for a skewed window, we have the following mesh:

int h;
int w;
CGPointWarp meshes[H][W];
for (h = 0; h < H; h++) {
    for (w = 0; w < W; w++) {
        CGPointWarp point;
        point.local.x = w * (frame.size.width / (W - 1));
        point.local.y = h * (frame.size.height / (H - 1));
        point.global.x = point.local.x + frame.origin.x + 15*h;
        point.global.y = point.local.y + frame.origin.y;

        meshes[h][w] = point;
    }
}

The skewed window would like this when the mesh was applied:

Applying the mesh

The transform mesh was really the hard part. Applying the transformation mesh (or grid) to a window is as easy as:

CGSSetWindowWarp(_CGSDefaultConnection(), [window windowNumber], W, H, meshes);

The possibilities of this are really amazing. I’ve always wanted to write an NSWindow subclass that bent and reduced in opacity as it was dragged, imitating XGL. With CGSSetWindowWarp and Core Graphics, I’m sure it’ll be a breeze. Or what about an virtual universe-style Finder cross Desktop, sort of like 3DOSX? You could even imitate other effects with this, such as the cube, but still get live updating in your windows - a limitation present in the Core Graphics transition effects.

For a source code, and a further explanation, see Kevin Ballard’s post on the subject of CGSSetWindowWarp.

Did you find this useful? Or do you have any other method that you use for eye candy?

Previously

We set up Xcode for Quicksilver plugin development, created a Quicksilver plugin project and got familiar with the QSPlugIn portion of the Info.plist file.

We’ve introduced ourselves to Quicksilver, and told it some fundamental information about the plugin we’re making in the QSPlugIn section of the Info.plist file associated with the Quicksilver project.

In this tutorial, we look at the procedures involved in specifying and writing an action for Quicksilver.

QSActions

Communicating our intentions

Writing an action for Quicksilver couldn’t be easier. In fact, there are only two steps in this “How to” guide. Firstly, it’s off to the all-important Info.plist; then we’ll finally begin writing our code.

You wont find a QSActions key in the Info.plist file. It’s named to QSActionsTemplate by default. This is to stop Quicksilver parsing the default data which is automatically added by creating a new project. If we’re writing an action, though, we’ll definitely want to make use of it.

Find the QSActionsTemplate key in the Info.plist file. It’ll look similar to the following, with the instances of “test” replaced with whatever you named your project:

    <key>QSActionsTemplate</key>
    <dict>
        <key>testAction</key>
        <dict>
            <key>actionClass</key>
            <string>testAction</string>
            <key>actionSelector</key>
            <string>performActionOnObject:</string>
            <key>directTypes</key>
            <array>
                <string>testType</string>
            </array>
            <key>name</key>
            <string>Action: test</string>
            <key>validatesObjects</key>
            <false/>
        </dict>
    </dict>

Make sure to rename the QSActionsTemplate key to QSActions. Configure the QSActions key as follows (remember “test” from now on is replaced with your project name):

testAction

Rename the testAction key to whatever you want to call your action. This is only internal - the user wont see this, but think of something that’ll tell you what this action does when you’re looking at it. We’ll call this the real name of the action. Descriptive names are especially important when working with multiple actions in a single plugin.

actionClass

You have the testAction class already created for you (in the testAction.h and testAction.m files). Double check that they exist and are identical to the value under actionClass.

actionSelector

If you’re going to have multiple actions or multiple methods, decide now what you’re going to call your method for this particular action and stick the value under the actionSelector key. If you’re only planning on having one action, the default performActionOnObject: should be fine. (If you want to have an indirect object passed to you as well, you’ll need a method in the form performActionOnObject:withIndirectType:. More on this later.)

alternateAction

If you wish to specify an alternate action, make sure you actually have another action in your plugin. Simply add a string with the name of the action to this key. Not the value for the name key, but the real name of the action.

directTypes

Add the types of inputs you want to be working with under the directTypes key. It’s an array of strings that can take values such as NSFilenamesPboardType, NSURLPboardType, NSStringPboardType or Apple URL pasteboard type. A list of allowed types includes:

• *
• Apple URL pasteboard type
• NSFilenamesPboardType
• NSStringPboardType
• qs.action
• qs.catalogentry
• qs.command
• qs.process

directFileTypes

If you’re using NSFilenamesPboardType as a directType and you only want files of a specific type, specify directFileTypes as an array containing strings with the extensions you want to allow (eg. png, pdf, app, etc.)

indirectTypes

Similar to directTypes, but only applies if you actually want an indirect object passed to your plugin.

indirectOptional

A boolean value specifying whether the selection of an indirect is required for the action to be called.

name

The name that the user will see when using your action from Quicksilver.

description

An (optional) brief description of what the action does.

enabled

A boolean value determining whether your plugin is enabled by default.

icon

An icon for your action. Can be in the form com.developer.app.

precedence

If you’d like your plugin to have more importance than other actions, enter an integer here. Normal settings are from 0 to 4. The higher the number, the more importance is given to your action. This is especially useful if your plugin deals with a source that no other plugin deals with. In that instance, you’d want your action to have higher authority than the standard ‘Open’ and ‘Run’ actions for that particular source.

reverseArguments

If set to true, Quicksilver will reverse the direct and indirect selectors before passing you the data. This comes in handy if you want to provide two actions that are the reverse of each other so you only need to write one method. For example, [Text] Find with... [Search Engine] is the reversed version of [Search Engine] Search For... [Text]. They both use the same selector, but the first one gets the direct and indirect objects swapped around.

displaysResult

If true, Quicksilver will take the value you return in your method, and set it as the direct object.

runInMainThread

Whether the action needs to be forced to run in the main thread. Recommended for timers or actions that calculate a delay.

hidden

Boolean specifying whether the action is visible (hence directly usable) by the user. This field is generally best left out unless you’re writing an internal action.

disabled

Whether the action is disabled by default when the plugin is activated. Boolean.

validatesObjects

True or false. True if your plugin validates the objects passed to it, false otherwise.

Now for some Cocoa

Writing the code

Yes, after having our head buried in the Info.plist, we finally get to write some code.

The class we declared as our actionClass in the Info.plist is the one that needs to house the method for the action.

Open up testAction.m (you still need to keep replacing ‘test’ with your project name). The file currently looks something like:

//
//  testAction.m
//  test
//
//  Created by Ankur Kothari on 15/02/07.
//  Copyright Vacuous Virtuoso 2007. All rights reserved.
//

#import "testAction.h"

@implementation testAction

- (QSObject *)performActionOnObject:(QSObject *)dObject{
    return nil;
}
@end

All you have to do, is take the QSObject which is passed to you in the form of the pointer dObject, do something with it, and return something! In fact, you don’t necessarily even have to return anything. This is the part of the tutorial that you put on your Cocoa hat and let your imagination, creativity and logic run wild. Write that amazing action!

If you don’t like to mess around until you’ve figured out how to do something, here’s an example of a Quicksilver action that takes a string object, then returns the same string with ” hello” appended to it. (Note that if you want to build the following code as a trial or test, you’ll need to configure the Info.plist using the information provided above.)

//
//  testAction.m
//  test
//
//  Created by Ankur Kothari on 15/02/07.
//  Copyright Vacuous Virtuoso 2007. All rights reserved.
//

#import "testAction.h"

@implementation testAction

- (QSObject *)performActionOnObject:(QSObject *)dObject{
    QSObject *result;
    NSString *dWithHello;

    dWithHello = [NSString stringWithFormat:@"%@ hello",[dObject stringValue]];
    result = [QSObject objectWithString:dWithHello];

    return result;
}
@end

Build and run

Double-click on the built plugin (test.qsplugin) to have Quicksilver install it. Passing a string such as “is this plugin working?” should get an output of “is this plugin working? hello“. Try passing a file or folder. The string you’ll get will be the name of the file / folder with ” hello” appended to it.

Take careful note of the following:

• The string is extracted from dObject using the stringValue method.
• An object of any type is extracted from dObject using … methods.
• An instance of a QSObject is created using the method objectWithType: where Type is the type of object you wish to add to the QSObject. Eg. [QSObject objectWithString:@"A string"];
• If the method returns a non-null value, it must be as a QSObject.

That’s it! You are now fully qualified to develop Quicksilver actions using Cocoa, in your familiar Xcode development environment.

If you’re very adventurous, look through the source code for other plugins you can find, and browse through the Info.plist files for some of the plugins you have (they’ll be a bundle with the extension of .qsplugin).

Have fun, and stay tuned for further tutorials on Quicksilver plugin development.

Also in this series

Info.plist - QSPlugIn

A introduction to the Info.plist and our first encounter with the QSPlugIn key. Teaches the initial steps required to ensure communication between Quicksilver and your plugin occurs correctly.

Quicksilver plugins in Objective-C

A guide to obtaining the required resources for Quicksilver plugin development in Xcode. Also runs through setting up Xcode to make creating plugins easier.

Quicksilver Interface Creation

A thorough guide on the techniques to create a working Quicksilver interface. Includes an Xcode project template to minimize the effort required.

We discussed the basic setup required to begin writing Quicksilver plugins in Quicksilver plugins in Objective-C. Anatomy of a plugin is a multi-section guide which explains the various sections of Info.plist, the different components of a plugin and the basic groundwork required in order to write a usable plugin.

To go through this guide, you need to have followed the steps in Quicksilver plugins in Objective-C. Once you’ve got Xcode set up properly for Quicksilver development, create a new Quicksilver plugin project in Xcode, and get ready to start planning your plugin.

Understanding Quicksilver’s plugin system

Info.plist

If you’ve worked with Cocoa or Objective-C, you may be familiar with the Info.plist file. As with any standard Cocoa application, the Info.plist file is an XML file specifying the various settings or options for the project in question. Quicksilver plugins use the Info.plist file to also communicate their features, actions and information to Quicksilver. It is in the Info.plist file that you need to begin editing, and realistically, you may well need to keep updating it as you add, remove, or delete features.

QSPlugIn

Tell me about you

The first thing you should probably fix up in the Info.plist file is the details that are unlikely to change. Find QSPlugIn, and take a look at it’s children. At the moment, it probably looks something like:

  <key>QSPlugIn</key>
 <dict>
    <key>author</key>
    <string></string>
    <key>categories</key>
    <array/>
    <key>description</key>
    <string></string>
    <key>icon</key>
    <string></string>
    <key>qsversion</key>
    <string>29CC</string>
    <key>relatedBundles </key>
    <array/>
 </dict>

The QSPlugIn section needs to be filled out accurately to inform potential users of its function. Lets go through the various keys that can be written inside QSPlugIn.

Author

The author is obviously you, so fill in your name.

<key>author</key>
<string>Ankur Kothari</string>

Categories

Categories is an array of strings corresponding to the appropriate categories as found in Quicksilver’s plugin preferences. You can have zero or more of the following:

• Applications
• Calendar
• Contacts
• Development
• Files
• Images
• Interfaces
• Mail & Chat
• Miscellaneous
• Music
• Quicksilver
• Search
• System
• Text
• Web

If you leave out the categories, then your plugin will still be under the “All plugins” section of Quicksilver, but wont show up under any category specific sections. For a plugin integrating MAMP support, the categories could be

<key>categories</key>
<array>
 <string>Development</string>
 <string>Applications</string>
 <string>Web</string>
</array>

Note: If you use the Mail & Chat category, make sure to escape the ampersand. It should be written as Mail & Chat

Description

The description is the text that is displayed in the info panel under the plugin preferences (unless an extendedDescription is set). Make sure you include the usage and function of your plugin in enough detail so potential users are aware of what it does. An example:

<key>description</key>
<string>Actions to start / stop the MAMP servers. Requires MAMP.app</string>

Extended Description

An extendedDescription is, as you would expect, a lengthier and more in-depth explanation of the plugin’s function. HTML is allowed in the extended description, but most characters must be encoded (For example, ‘<’ becomes ‘<’ and ‘>’ becomes ‘>’). If an extended description is set, it is shown in the info panel under Quicksilver’s plugin preferences. This field is optional. An example of an extended description (taken from the Apple Mail plugin):

<key>extendedDescription</key>
<string>Enables email actions for <a href="http://www.apple.com/macosx/features/mail/">Apple Mail</a>.
Allows browsing mailboxes as children of Mail (beta)</string>

Icon

The icon can be in the form com.developer.app (such as com.apple.Mail or com.apple.iTunes) or <speculation> you can write the name of an image that you’ve imported into your Xcode project </speculation>. This field is not required. If left blank, Quicksilver will assign your plugin an icon. The icon for the Mail plugin reads:

<key>icon</key>
<string>com.apple.Mail</string>

Hidden

A boolean value specifying whether the user can see this plugin in the plugin list or not. Generally only used by internal Quicksilver plugins. The Core Support plugin (bundled in Quicksilver.app/Contents/PlugIns/) has hidden set as:

<key>hidden</key>
<true/>

There is also a boolean key called secret, but it’s obviously, well, secret.

Related Bundles

Related bundles refers to resources or packages that are similar to or related to this plugin. The Mail plugin’s related bundle key reads:

<key>relatedBundles</key>
<array>
    <string>com.apple.Mail</string>
</array>

Required Bundles

requiresBundle is optional and if set, doesn’t allow the plugin to be used unless the specified package is currently also installed. A human-readable version of this value will automatically be shown under the heading “prerequisites” in the plugin info panel. The key is in the form com.developer.app and may look something like

<key>requiresBundle</key>
<array>
    <string>com.flyingmeat.VoodooPad</string>
</array>

webIcon

webIcon is again optional, and may be set to the URL of an image. For example, the Cyberduck module sets the webIcon to a png using the following code:

<key>webIcon</key>
    <string>http://quicksilver.blacktree.com/public/ytrewq1/Cyberduck.png</string>

Info File

If you’d like a readme file associated with your plugin, you can create a simple text or rich text file (.txt or .rtf) and import it into your Xcode project. Then it’s a simple matter of specifying this as file as the infoFile. An example:

<key>infoFile</key>
<string>Info.rtf</string>

Currently, I don’t think the infoFile is actually accessible through Quicksilver’s interface, but it seems likely that the “?” button in the plugin info panel would be used to display it in future versions.

Overwhelmed? Don’t be. There’s really no need to specify all of the above keys in the QSPlugIns section of the Info.plist. Author, categories, and description are the basic necessities, and anything beyond that is a bonus.

So if you haven’t already done so, decide on what your Incredible Plugin™ is going to do, and fill out the QSPlugIn portion of the Info.plist. Then take a break and relax while you wait for the next section in this series!

Also in this series

Quicksilver Actions

A quick look at QSActions in the Info.plist, followed by our first look at the code needed to get a plugin up and running.

Quicksilver plugins in Objective-C

A guide to obtaining the required resources for Quicksilver plugin development in Xcode. Also runs through setting up Xcode to make creating plugins easier.

Quicksilver Interface Creation

A thorough guide on the techniques to create a working Quicksilver interface. Includes an Xcode project template to minimize the effort required.