Bug fixes

A lot of features were buried in the source, available only by setting some preferences to allow them. Mostly it was due to buggy implementation or pending improvements. I managed to resurrect a few of these nifty ones and fix a few old bugs that have annoyed me for ages.

Color handling

Color handling was commented out in the Quicksilver source; probably because it resulted in errors. A simple change in the source allowed correct handling of color values, and the code for drawing the icon was already there. I added functionality to allow dropping colors from the Quicksilver object pane into color wells and the like - which is what makes this useful.

Uninstalled plugins

Added a plugin set to the plugins preference pane to list plugins that you haven’t yet installed or downloaded. Not sure why this was commented out; I didn’t have to add any new code here.

Triggers

There was a very annoying bug in the triggers preference pane that haunted me from the day I started using Quicksilver. Switching to the iTunes trigger set resulted in errors, and often froze or messed up Quicksilver. Finally, it’s fixed, and we can see and use these triggers.

Speaking of plugins; I think I heard mention of a “plugin check bug” fixed somewhere, but it wasn’t working for me so I’ve also fixed the issue where the plugin list would be blank until you hit refresh.

Miscellaneous bug fixes

Other things like crashing when you try to relaunch with the “Customize” preference pane open, and with the source, hundreds of warnings when trying to compile, errors in the shell scripts when working in a path with non-alphanumeric characters, etc. have also been fixed.

Tidy up

[I wonder] how long it’ll take people to notice the Frankensteinian nature of the source and respond - appropriately - with pitchforks. Alcor

I’ll have to agree with Alcor - to say the source is a mess would be an understatement. There are hundreds of compiler warnings, unused or unimplemented features, classes, objects, code, structures, nibs, etc. Hundreds. I’ve tried to remove as much of the redundant or test code as possible and I’ve yet to reach the end. Mind you, I’ve been doing this for hours a day for the past week. The formatting and indentation is almost as bad. I’m cleaning that up too, with some good old regular expressions and elbow grease. As I go, I’m also trying to improve the logic where I see potential for improvement. Already the application is feeling more responsive but I want to also reduce the memory footprint.

Why go to all this trouble? Mainly, to

• Make the source more readable; make it easier for people to understand what’s going on.
• Improve the performance of the application in both speed and memory usage.
• Fix existing bugs and add new features.

In the meantime, I’ll continue my clean up of the Quicksilver source and when it’s lookin’ fine perhaps post it up (the QS license doesn’t really say much about the source, so I might have to ask Alcor first. Perhaps he’d like to add it to the subversion repository after reviewing?).

Lastly, let me just say, I’ve learnt a lot from looking at the source code to Quicksilver. There are some very neat tricks in there, and great little snippets that could be very useful elsewhere. So thank you Mr. Jitkoff; thank you for writing the application, and thank you for the releasing the source code. It is highly appreciated.

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.

Here’s your answer.

AppleScript can be handy sometimes, but when people release applications like this, and get awards for it, alarm bells should be going off. WallSaver is almost two megabytes in size. For a single command-line.

Just reinforce the point, I wrote another wrapper for the same command in Objective-C. It’s 100 kb, or 60 kb without the icon. It can pause the screensaver (which brings it down to 0 CPU usage), resume it or restart it. And not once will it throw an “AppleScript error” . Download it and see for yourself.

As for the source code, all you need is:

/System/Library/Frameworks/ScreenSaver.framework/Resources/ScreenSaverEngine.app/Contents/MacOS/ScreenSaverEngine -background

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.

The reason for this article should be obvious: too many OS X third party developers do an absolutely terrible job of building and packaging their applications. rixstep

Too many apps are shipped with debug symbols, uncompressed images, redundant files or generally useless rubbish that not only wastes users’ disk space, it ultimately ends up increasing the developer’s own bandwidth costs.

It’s not just the script kiddies at fault. Path Finder weighs in at over 60 MB on disk, but after a few simple operations, is halved in size to just over 30 MB. AppZapper can be trimmed from three megabytes to just one. Xslimmer (ironically) is over 80% junk, going from 5 MB on disk to a meagre 1 MB after being cleaned. In this case, the disk image is three times as big as the cleaned, uncompressed app. Starting to see the trend? Almost every app can be cleaned up to save a good deal of space.

Deploying your app

Rixstep provide instructions on deploying OS X apps covering most of the major areas.

Essentially, you need to:

Remove Junk

Get rid of all .DS_Store files. In Cocoa apps, remove PkgInfo. You should only have objects.nib or keyedobjects.nib in your nibs: remove classes.nib, info.nib, and data.dependency; these are not relevant for the user. Also remove all header files from your app and from embedded frameworks.

Clean up localization

Keep all non-language-specific resources in the Resources folder rather than duplicating them in each .lproj folder. Look through the framework you’re embedding, and remove any unnecessary files files. That includes language projects which your main app doesn’t support.

Compress images

Make sure all your images are compressed, especially if they’re in TIFF format. (But you shouldn’t use images for simple graphics like curves or gradients anyway; there are Cocoa drawing routines for that and NSBezierPath is your friend)

Trim binaries

Do not release an app that has been built using the Xcode “Debug” configuration. Remove the debug symbols from your build product, and if possible, release architecture-specific versions of your app, as well as a universal binary.

Get all the details in Building and Packaging Native OS X Applications.

Automation

A relevant question is: are there any tools that automate this process? And the answer has to be ‘not up to now there aren’t’. Until something comes along to save users from these issues it’s still all up to that developer you trust. Rixstep

There is finally a tool that automates at least some of the cleaning process. Say hello:

Go get trim-app

Trim-app is a shell script. It:

• Cleans out all the horrible .DS_Store files
• Removes unnecessary info.nib, classes.nib, and data.dependency files from inside nibs
• Strips “fat” universal binaries to contain code for a chosen architecture only
• Eliminates debug symbols that may be left in your application

You can perform all procedures at once, one at a time, multiple at a time, etc. using different parameters or flags (run trim-app -h for help).

The script searches the current working directory including every subdirectory so no files are missed. Even embedded frameworks are scanned through and cleaned out. So make sure you’re in the right directory before running (use the pwd command if unsure)

All changes performed are permanent and non-recoverable. (If you’re writing the app, that shouldn’t be a problem. Just build it again if something goes wrong)

While it’s written for cleaning out applications, this script is also great for general tasks - cleaning out .DS_Store files in a certain folder, for example.

Installation

• Unzip the download.
• Open Terminal and navigate to the folder where the unzipped trim-app is.
• Run chmod 0700 trim-app. This makes sure only you can execute it.

If you want easy access to the command, move the file to /usr/bin/ by running sudo mv trim-app /usr/bin/. You’ll be asked for the admin password, then file will be moved.

You can now test if it’s working by running trim-app -h. Instructions for trim-app will appear. Once you’re done reading them, press q to exit, and start using it!

Usage

Running the shell script without any parameters will attempt to run all four procedures. You’ll be prompted for an architecture to keep in universal binaries. Leave this blank (just hit return) to leave universal binaries universal, or type in an architecture to keep (usually ppc or i386) if you want them stripped down.

Here’s an example of how you would use it in the Terminal:

% cd myApp.app/
% trim-app
Architecture to keep? (ppc/i386) ppc
   Removing .DS_Store files…
   Trimming nibs…
   Trimming universal binaries…
   Stripping debug symbols…
   Cleaning up…
Done.
%

If you don’t want to be prompted each time for the architecture, use either --all (as in, trim-app --all) (which will run everything except the liposuction of universal binaries), or add the architecture to keep immediately after, like trim-app --all ppc.

Add a -p flag to the end if you want to see a list of affected files. For example,

% trim-app --all i386 -p

You can also run individual procedures. The following cleans out .DS_Stores from the entire Macintosh HD:

% cd /
% sudo trim-app -d

Run trim-app -h to find out more about the available parameters.

Don’t forget the standard shell practices still apply. Ctrl-C any time during operation to immediately halt execution, save output to a file with trim-app -p > trim-log.txt, and so on.

Lastly, remember that while this shell script does a lot of the work (and there is an application called CleanApp which can help remove unnecessary lproj files), it’s still up to you to take care of removing headers, compressing images, etc.

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.

There’s absolutely no documentation on how to write an internal command for Quicksilver anywhere and figuring out the internal workings of the application can be frustrating at best. This tutorial aims to fill that void and, like some of my other Quicksilver-related articles, provide you with the knowledge and resources to make a working internal command.

Prerequisites

An internal command is written much like a standard Quicksilver action, so the only thing required is the Xcode project template for creating Quicksilver plugins. (However, if you really need another project template for writing internal commands, just ask)

It would also be a good idea to familiarize yourself with writing a Quicksilver action before going on.

Info.plist keys

Somewhere in the plist, you need to set QSLoadImmediately to true for Quicksilver to load your internal command properly. That’s simply:

<key>QSLoadImmediately</key>
<true/>

To register our internal command with Quicksilver, we need to add QSInternalMessages to the QSRegistration key. So, find the QSRegistrationTemplate key, rename it to QSRegistration, and configure the command in the following manner:

<key>QSRegistration</key>
<dict>
    <key>QSInternalMessages</key>
    <dict>
        <key>testInternalCommand</key>
        <dict>
            <key>target</key>
            <string>testCommand</string>
            <key>action</key>
            <string>doTestCommand:</string>
            <key>name</key>
            <string>Just a Test</string>
            <key>icon</key>
            <string></string>
        </dict>
        ...

What do the keys mean?

target

The class that will be running the internal command. This needs to be a singleton. More on that later.

action

An instance method that the target class responds to; this is the command.

name

A brief and meaningful name for your internal command.

icon

An icon for your command. You can use an identifier like com.blacktree.Quicksilver or com.apple.AddressBook and Quicksilver will load up the appropriate icon for you.

The class

As I mentioned earlier, the class that runs the command should be a singleton - that means only one copy of the class is instantiated and used (Apple’s documentation on singletons). The internal command will be called like: [[targetClass sharedInstance] doActionMethod:nil] where targetClass is the class you specified under target and doActionMethod: is the method for the key action in the Info.plist.

From the example Info.plist excerpt given above, the class that would be written would look something like this:

// testCommand.h

#import <QSCore/QSActionProvider.h>

@interface testCommand : QSActionProvider
{
}
+ (id)sharedInstance;
-(IBAction)doTestCommand:(id)sender;
@end

// testCommand.m

#import "testCommand.h"

@implementation testCommand

// Following few methods to make this class a singleton

static testCommand *sharedTestCommandManager = nil;

+ (id)sharedInstance {
    if (sharedTestCommandManager == nil) {
        [[self alloc] init]; // assignment not done here
    }
    return sharedTestCommandManager;
}
+ (id)allocWithZone:(NSZone *)zone{
    //    @synchronized(self) {
    if (sharedTestCommandManager == nil) {
        sharedTestCommandManager = [super allocWithZone:zone];
        return sharedTestCommandManager;  // assignment and return on first allocation
    }
    //      }
    return nil; //on subsequent allocation attempts return nil
}
- (id)copyWithZone:(NSZone *)zone{
    return self;
}
- (id)retain{
    return self;
}
- (unsigned)retainCount{
    return UINT_MAX;  //denotes an object that cannot be released
}
- (void)release{
    //do nothing
}
- (id)autorelease{
    return self;
}

// Method to perform the internal command

-(IBAction)doTestCommand:(id)sender
{
    NSLog(@"Running test internal command...");
    // do something useful
}

@end

And that’s it. Possibly the shortest ever Quicksilver development tutorial you’re going to see in a while.

I thought I’d drive home the usefulness of internal commands by showing off a little something I’ve been playing with for a while.

A simple internal command allows any interface to smoke

Yeah, it’s the cube interface. Smoking.

In fact, with this internal command, I can make anything smoke.

Summary

• Add QSLoadImmediately key, set to true
• Add QSInternalMessages to the QSRegistration key
• Write singleton class that runs the command

As always, I’ll be thrilled to see what you come up with.

Standard Animation Effects

Quicksilver adds a category to the NSWindow class to allow for some pretty cool effects. The following should be pretty self-explanatory:

-(void)pulse:(id)sender;
-(void)flare:(id)sender;
-(void)shrink:(id)sender;
-(void)fold:(id)sender;

What these methods essentially mean, is that you can pulse, flare, shrink or fold any window you have a reference to in a plugin - whether it’s an interface or dialog or something completely different. Eg, just call [window shrink:nil] and watch that NSWindow shrink down to nothing, or [window flare:nil] to make it burst away!

Private Core Graphics Animations

Quicksilver also adds methods to use private Core Graphics transitions for instances of NSWindow or its subclasses. The main method is defined something like:

- (void) displayWithTransition:(CGSTransitionType)type option:(CGSTransitionOption)option duration:(float)duration;

The transitions you have access to are fade, zoom, reveal, slide, warp-fade, swap, warp-switch and the famous cube animation. You can use them on any window, for example:

[window displayWithTransition:CGSCube option:CGSLeft duration:1.3];

To learn more about Core Graphics transitions, see the Core Graphics ebook, or play around with the Core Transitions Framework.

Quicksilver’s CGSPrivate.h file is missing CGSFlip, but you can run the Dashboard-style flip effect by using the integer 9.

Quicksilver’s own animations

Alcor has used various techniques to write several very interesting animation effects into Quicksilver. You’ll be familiar with some of these (just watch the Primer interface activate and deactivate) but for whatever reason, many of these bizarre animations never made into an interface. They’re really very clever. I’ve played around with some of these:

• QSGrowEffect
• QSShrinkEffect
• QSSlightGrowEffect
• QSSlightShrinkEffect
• QSBingeEffect
• QSPurgeEffect
• QSExplodeEffect
• QSExtraExtraEffect
• QSShakeItLikeAPolaroidPictureEffect
• QSBoobTubeEffect
• QSVExpandEffect
• QSVillainousKryptonianEffect
• QSMMBlowEffect
• QSLudicrousSpeedEffect

Very interesting to look at, but how does one use these effects?

As we are dealing with Quicksilver, the solution is (as expected) very elegant. There are very simple methods to set a show, hide or execute effect for a window. These methods don’t even require an explanation; they’re so simple:

// Effect for showing the QSWindow
[window setShowEffect:[NSDictionary dictionaryWithObjectsAndKeys:@"QSSlightGrowEffect",@"transformFn",@"show",@"type",[NSNumber numberWithFloat:2.0],@"duration",nil]];

// Effect for hiding the QSWindow
[window setHideEffect:[NSDictionary dictionaryWithObjectsAndKeys:@"QSSlightShrinkEffect",@"transformFn",@"hide",@"type",[NSNumber numberWithFloat:2.0],@"duration",nil]];

// The "execute" effect is slightly different:
[window setWindowProperty:[NSDictionary dictionaryWithObjectsAndKeys:@"QSExplodeEffect",@"transformFn",@"hide",@"type",[NSNumber numberWithFloat:1.5],@"duration",nil] forKey:kQSWindowExecEffect];

Easy!

Sample plugin

I don’t dare mention all this private goodness and not even provide a demonstration. I’ve created an “Effects” plugin that will allow you to change the activate, deactivate and execute effects for any Quicksilver interface temporarily to play around with the effects. Just for good measure, I’ve also thrown in an action that lets you explore Core Graphics transitions as well.

This is not really a bona fide Quicksilver plugin; while it does let you have some fun with the effects, it’s not very user-friendly and doesn’t save your configuration. If these animations prove to be popular, then I’ll write a proper plugin to let you configure the effects more easily (probably through a preference pane) and remembers your settings.

Download Quicksilver Effects Plugin

Usage

Type in the name of the effect you want, then use “Set Hide Effect”, “Set Show Effect” or the “Set Exec Effect” action. The list of effects is given above; just type one in and run the relevant action.

To run a Core Graphics transition, type in the name of the transition, and use the “Run CoreGraphics Transition” action. You can optionally specify a direction in the indirect selector. (You can enter text in the direct and indirect selectors by pressing the period “.” key)

For example

• “QSBingeEffect” -> Set Show Effect
• “QSPurgeEffect” -> Set Hide Effect
• “QSExplodeEffect” -> Set Exec Effect
• “flip” -> Run CoreGraphics Transition
• “slide” -> Run CoreGraphics Transition -> “up”
• “swap” -> Run CoreGraphics Transition -> “inout”

Pictures show how to use the effects plugin. Actual animations are not shown.

Quicksilver has many such hidden surprises and nifty time-saving methods; it’s so well thought out and full of these amazing gems!

What do you think about these animations? Be sure to let me know if you’d like a proper, more user-friendly plugin to use these effects.

Writing an interface is very similar to writing an action, but the classes and Info.plist keys are somewhat different. Download the QS Interface Project Template. If you haven't previously downloaded a Quicksilver plugin template for Xcode, you'll have to do some basic setup.

Once you've installed the project template, you can build a new interface project "out-of-the-box" to make sure it works.

Unfortunately, development isn’t a linear process, so you’ll probably have to keep referring back to different sections of this article as you develop your interface.

Info.plist keys specifications

We tell Quicksilver that we're providing it an interface in the QSRegistration section of the Info.plist file, under QSCommandInterfaceControllers. By default, this should have been already added in when you created the project.

<key>QSRegistration</key>
<dict>
    <key>QSCommandInterfaceControllers</key>
    <dict>
        <key>testInterface</key>
        <string>testInterface</string>
    </dict>
    . . .
    . . .
</dict>

There is also a key called QSPreferencePanesTemplate inside QSRegistration. If you wish to have a preference pane for your plugin, rename the key to QSPreferencePanes and create the pref pane; otherwise you can leave it or delete it. As per the previous setting, these values should be filled in already by the project.

<key>QSRegistration</key>
<dict>
    . . .
    . . .
    <key>QSPreferencePanesTemplate</key>
    <dict>
        <key>testInterfacePrefPane</key>
        <dict>
            <key>class</key>
            <string>QSPreferencePane</string>
            <key>description</key>
            <string>testInterface interface preferences</string>
            <key>icon</key>
            <string></string>
            <key>name</key>
            <string>testInterface</string>
            <key>nibBundle</key>
            <string>com.blacktree.Quicksilver.testInterface</string>
            <key>nibName</key>
            <string>testInterfacePrefPane</string>
            <key>type</key>
            <string>hidden</string>
        </dict>
    </dict>
</dict>

If you're not having a preference pane, you should remove the PrefPane.nib file from your project when you're ready to release your plugin; it'll save bandwidth as well as reduce clutter.

You may not have an idea of the bindings you’ll be using yet (or maybe you do), but when you do use them, it's good practice to specify some default values for Quicksilver to use when the value hasn't been set by the user. These values go in the QSDefaults key.

<key>QSDefaultsTemplate</key>
<dict>
    <key>interface.bindingname</key>
    <string>value</string>
    <key>interface.bindingname2</key>
    <real>2.54328</real>
    <key>interface.bindingname2</key>
    <integer>4</integer>
</dict>

If you're using the "QSDefaults" key, make sure you’re renamed it from "QSDefaultsTemplate" to "QSDefaults".

Don’t forget there’s also a QSPlugin section in the Info.plist file that you should fill in.

Coding

That's the Info.plist file out of the way for now. It's time to start coding!

There are a few basic Quicksilver terms I hope you're familiar with:

Fig 1. The selectors are the used to pick the direct object, action, and indirect object respectively. Indirect object is often optional or not required.

Arrangement and positioning of the views using Interface Builder is left as an exercise for the reader. You don't want a lesson on how to drag and drop, do you?

Controlling the Controller

As mentioned before, the superclass (QSResizingInterfaceController) handles most of the work for you, therefore the majority of code you add will not be in new methods. Most of the code you write is (probably) going to be in existing methods that you will subclass.

Major methods

Here are the main methods you may decide to add extend:

- windowDidLoad

Anything that requires interaction with the interface window when it is first loaded. As the name implies, this method is called when the interface window is first loaded. All your setup with the window goes in this method. For example, setting the colors, adding bindings, and choosing animation effects for hiding / showing the interface etc. Please make sure you call [super windowDidLoad]; somewhere to let Quicksilver to do its setup as well.

This is not the place to add initialization code for the class itself. There's an -init method for that.

- maxIconSize

The maximum size allowed for icons in the interface selectors. Adjust this depending on how big or small your interface is. It's set at 128 x 128 by default, which should be fine in most circumstances.

- showMainWindow:

Any fancy animations or transitions you want for when the interface is being shown can go in here. You could also do something like: if ( [[self window]isVisible] ) [[self window] pulse:self];. (The pulse method is explained later). If you're having your own transition effect and don't want Quicksilver's default fade-in animation, run [window setFastShow:YES].

If you can, call the super implementation of the method where you would call -makeKeyAndOrderFront:, otherwise the option to suppress hotkeys while the command window is shown wont be honored.

- hideMainWindow:

Calling the super's implementation will hide the window with Quicksilver's effect. If you're using your own animation, you can run [window setHideEffect:nil] so Quicksilver doesn't run its own effect as well.

- activateInTextMode:

The use of the "Activate in Text Mode" trigger may be a rare occasion, but it's a cool place to throw in a surprising animation. Fumo has used Core Graphics warp and cube effects for this in the past.

Expansion

If you're having your interface expand and collapse, you'll need to subclass the following methods:

- showIndirectSelector:

Position the indirect selector in an appropriate location on the window. It may be useful to position it relative to another object, for example: [iSelector setFrame:NSOffsetRect([aSelector frame],0,-250)]; Don't forget to call super!

- expandWindow:

Expand your interface. You'll probably be using [[self window] setFrame: display: animate:] to resize the window smoothly.

- contractWindow:

As per -expandWindow:, but make the window smaller.

-hideIndirectSelector:

In most cases you wont need to subclass this. It just hides the indirect selector.

Preference Panes

The easy stuff

Creating your preference pane is easy since a lot of the work is done for you by the project template. There's a .nib file included in the interface project called "testInterfacePrefPane" (where "testInterface" is the name of your Xcode project). With this .nib file:

1. Open it.
2. Add controls and bindings.
3. Save and quit.

That’s creating it, though. There's still a little more work to be done.

Info.plist keys

Remember the QSPreferencePanes key I mentioned earlier? That needs to be present under the QSRegistration key in the Info.plist file. You don’t need to configure it, but you can change some keys like description with a short summary of the preference pane, or set an icon.

(Reminder: Make sure to drop the "Template" from "QSPreferencePanesTemplate")

The "Customize" button

To set a customize button to show the preference pane for your interface, simply uncomment the -customize: method that's added in by default. It’s that easy.

- (IBAction)customize:(id)sender{
    [[NSClassFromString(@"QSPreferencesController") sharedInstance] showPaneWithIdentifier:@"testInterfacePrefPane"];
}

A note on bindings

When the user changes something in the preference pane, the binding will be updated. And that’s it. You’ll need to bind your classes / controls not only in the preference pane, but also in your code so that any changes to bindings reflect in your interface. For example, if you add a binding for "testInterface.fadeStyle", you may want to do something like:

[self bind:@"fadeStyle"
     toObject:[NSUserDefaultsController sharedUserDefaultsController]
  withKeyPath:@"values.testInterface.fadeStyle"
      options:nil];

If you’re binding an NSColor, make sure to use NSUnarchiveFromDataTransformerName

Building

Once you’ve got your code ready, build the project.

(Don’t puke if you get warnings that you can’t get rid of; there will be a few warnings regarding some methods like -setWindowProperty:, and another great error if you add a preference pane and the customize button. We’ll have to live with them for now.)

Double-click on the built product to have Quicksilver install it. If there are no serious faults with the code, you’ll see your Incredible Interface™ and be able to enjoy, use, and distribute it!

Summary

• Download the Xcode Project Template, making sure everything else is setup correctly
• Add code to the subclass of QSResizingInterfaceController
• Arrange the views in Interface Builder
• Add preference pane and bindings
• Build project
• Test and distribute

If you need any additional information or resources, help is always available at the Quicksilver forums or you can contact me.

Be sure to show me how you go with your interface!

Also in this series

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.

Info.plist - QSPlugIn

The various sections of Quicksilver plugins, including the basics on how to properly configure your plugin, setup the correct options and settings, and how and where to write your plugin.

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.