Note that this requires version 0.2.5 of Safari Tidy, which was just released today.

Download

Method Swizzling is one common technique of people writing hacks, such as Safari Plugins. Unfortunately, it’s always suffered from a flaw, wherein swizzling inherited methods affects all classes which inherit that method (including the base class), rather than the intended subclass. This problem is discussed on the CocoaDev Method Swizzling page.

As part of writing YubNubSearch, I decided to solve this problem.

First I looked into dynamic subclass generation + posing. Unfortunately, this has a big problem. In this technique, calling the original implementation would naturally be done through a [super foo] call. Unfortunately, when the compiler sees super, it hardcodes a reference to the superclass at which to start the search. This means you cannot write this code in, say, a category on NSObject, then pull up the IMP into a dynamically-generated subclass and have it work. So that throws out that idea.

The other idea I had, which I eventually went with, was to copy inherited methods into the subclass that you wish to swizzle, before swizzling. It turned out to be fairly easy, and still has the same semantics as the old, flawed technique for calling the original implementation.

You can download my implementation here.

You can get it here.

For those not in the know, MacPorts (née DarwinPorts) is an open-source package manager for Darwin (although it should work with other *nixes, it’s really intended for Darwin). I’ve been using it for quite some time, and even contributed a few Portfiles a while ago. Well, I started poking at it again recently, and then jmpp on #macports convinced me to apply for a commit bit.

Now I just gotta do something to justify this shiny new bit.

Objective-C has a method caching mechanism that optimizes for the case where a small number of methods are called repeatedly on one (or more) objects of a given class. This happens very often; for example, if you iterate over an array to gather the results of performing an operation on each element, you’re going to be calling the same method on a bunch of instances of the same class. And in fact the -[NSEnumerator nextObject] method itself will also be cached.

The fact that method caching exists is common knowledge. However, what isn’t generally known is how that caching is implemented, and what it means for you if you want to hack around on the internals of a class.

Objective-C Method Caching

The biggest reason why people might care about Objective-C method caching is if they’re doing what’s commonly termed “Method Swizzling”. This is where you take two methods with the same signature (same return value and argument types), and you swap them so any code that tries to call the first will really call the second, and vice versa. The primary use of this is when you want to patch an app you have no control over - you can use a category to add a new method to the class, then swizzle that with the original method.

The reason why this is a potential issue is, since nobody knows how the method caching actually works, nobody knows if Method Swizzling can be affected by the method caching.

Well, the short answer is no.

Objective-C method caching works via a miniature hash table (of type struct objc_cache) stored in the cache field in every struct objc_class. This hash table contains pointers to recently-used Method objects, which are the same Method objects as found in the struct objc_method_lists on each struct objc_class. The important part here is the cached Method objects on a given class can actually belong to one of the class’s superclasses. This is what makes the caching really useful — the method dispatch system doesn’t have to trawl upwards through the class hierarchy to find the method if it’s already been cached.

The reason why Method Swizzling doesn’t have to worry about method caching is because of the fact that the cached Method objects are the same ones from the struct objc_method_lists in each class. When Method Swizzling modifies the Method object, the cache is modified at the same time, so any subsequent cache hit will reflect this modified Method.

If for some reason you want to flush the cache for a class (and I can’t think of why), simply insert

void _objc_flush_caches(Class cls);

somewhere in your file and then call it, passing the class you wish to flush the cache of. This particular method will also flush the cache of every superclass of the given class.

Method Swizzling

If you want to use Method Swizzling in your own app (or Input Manager, or SIMBL plugin, or…) the following implementation is the best one I’m aware of.

void PerformSwizzle(Class aClass, SEL orig_sel, SEL alt_sel, BOOL forInstance)
{
    // First, make sure the class isn't nil
    if (aClass != nil) {
        Method orig_method = nil, alt_method = nil;

        // Next, look for the methods
        if (forInstance) {
            orig_method = class_getInstanceMethod(aClass, orig_sel);
            alt_method = class_getInstanceMethod(aClass, alt_sel);
        } else {
            orig_method = class_getClassMethod(aClass, orig_sel);
            alt_method = class_getClassMethod(aClass, alt_sel);
        }

        // If both are found, swizzle them
        if ((orig_method != nil) && (alt_method != nil)) {
            IMP temp;

            temp = orig_method->method_imp;
            orig_method->method_imp = alt_method->method_imp;
            alt_method->method_imp = temp;
        } else {
#if DEBUG
            NSLog(@"PerformSwizzle Error: Original %@, Alternate %@",(orig_method == nil)?@" not found":@" found",(alt_method == nil)?@" not found":@" found");
#endif
        }
    } else {
#if DEBUG
        NSLog(@"PerformSwizzle Error: Class not found");
#endif
    }
}

void MethodSwizzle(Class aClass, SEL orig_sel, SEL alt_sel)
{
    PerformSwizzle(aClass, orig_sel, alt_sel, YES);
}

void ClassMethodSwizzle(Class aClass, SEL orig_sel, SEL alt_sel)
{
    PerformSwizzle(aClass, orig_sel, alt_sel, NO);
}

This particular implementation swaps the method_imp pointers on the two methods, so calling the first method will call the original implementation of the second, and vice versa. The elegant aspect to this is when you want to call the original method — simply call your new method again. The following example, adapted from SafariSource, demonstrates this.

- (void) mySetString:(NSString *)string {
    NSUserDefaults *defs = [NSUserDefaults standardUserDefaults];
    if ([defs boolForKey:SafariSourceEnabled]) {
        // do stuff here
    } else {
        [self mySetString:string];
    }
}

When any code tries to call setString: on this class, the swizzled method mySetString: is called again. But since the swizzling is done in both directions, trying to call mySetString: will in fact call setString:. So when the code appears to be calling itself recursively, it’s really calling the original function.

The biggest flaw with this implementation (and any others I’ve seen) is that if you want to swizzle a method that’s actually implemented in a superclass, the swizzling will affect all instances of that superclass instead of just instances of the subclass. There are a couple of possible solutions, such as dynamically creating a new class and using it to pose as the old class, but none have yet been implemented to my knowledge.

First, some history. CoreGraphics has a bunch of private calls that range from applying transitions to windows (such as the cube effect seen in Apple Remote Desktop and Quicksilver) to managing virtual desktops to setting alpha levels on groups of windows system-wide. As far as I am able to ascertain, Richard Wareham did the bulk of the work to expose these calls, as part of development on his Desktop Manager program, the most well-known virtual desktop solution for OS X. He released a file named CGSPrivate.h that contained these basic calls, so others could use it. Since then, more private calls have been discovered, and among them were CGSSetWindowWarp().

For a while, only the name of the function was known. As far as I know, I was the first person to determine what the arguments to the function were, though this information wasn’t widely disseminated. Instead, I simply told Nicholas Jitkoff (author of Quicksilver), as he was the one who asked me to help him figure it out. At that time, I didn’t know how the function was actually used, I just knew what arguments it took. And then I forgot about it.

Since then other people have played with the function (having figured out the arguments on their own). The most visible documentation of this I could find was on CocoaDev, where the author of the splendid Rotated Windows sample app said he figured out the arguments to the function but hadn’t yet figured out how it was actually used - basically, he did what I did.

At this point, what was known was the method signature:

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

extern CGError CGSSetWindowWarp(CGSConnectionID, CGSWindowID, int w, int h, CGPointWarp mesh[w][h])

Most of this is pretty self-evident, but the tricky question is how the mesh works.

Well, some time ago I ran across a sample app called warp.c, which simply produced a simple animation of a window being bent backwards (using a bezier curve). It wasn’t very complex, but it did help show how the deformation mesh was constructed. What the mesh does is maps local window coordinates to global screen coordinates. It’s a 2-dimensional array that forms a grid of points. From what I can determine, the local points are expected to form a regular, even grid. The vertical and horizontal deltas can be different, but they must be consistent. Changing a single point causes visual issues, from simply incorrect drawing to the window disappearing.

Based on this, I was able to construct my entry for ironcoder that used CGSSetWindowWarp() as the main effect.

To summarize, the way CGSSetWindowWarp() is used is the mesh is a 2-dimensional grid of local points with associated global points. The local points are in the window’s coordinate system, whereas the global points are in the screen’s coordinate system.

One pitfall I discovered during this process is you need to be aware of the window being dragged. If you’re animating a window and someone starts to drag it, you can run into problems where the window keeps snapping back to its old location. Why is this? Because -[NSWindow frame] doesn’t update until you end the drag, so your global coordinates are going to be based on the window’s old position. Not to mention -[NSWindow frame] uses a flipped screen coordinate system from CGSSetWindowWarp(). There’s a good solution to this, however. That solution is to use another private method:

extern OSStatus CGSGetWindowBounds(CGSConnectionID cid, CGSWindowID wid, CGRect *bounds)

This will give you a CGRect (structurally and functionally equivalent to an NSRect) that contains the current frame of the window, taking a current drag into account, and using the same coordinate system that CGSSetWindowWarp expects. There’s also another similar function:

extern OSStatus CGSGetScreenRectForWindow(CGSConnectionID cid, CGSWindowID wid, CGRect *outRect)

There is one crucial difference, namely, that the CGRect given by this function is the rect that covers the entire rendered area of the window, meaning any window mesh deformations are taken into account. So this is not the right function to use when calculating the deformation mesh, because any pre-existing deformation will throw off the coordinates. So use CGSGetWindowBounds() always.

The last bit of information necessary to use CGSSetWindowWarp() is how to get the CGSConnectionID and CGSWindowID. This, luckily, is extremely simple. A CGSConnectionID can be retrieved with the private function:

extern CGSConnectionID _CGSDefaultConnection()

and the CGSWindowID is the result of calling -[NSWindow windowNumber] on your window. Incidentally both CGSConnectionID and CGSWindowID should be typedefs of int.

You should be aware that applying a deformation mesh to a window will cause the shadow to not draw. So if you want a normal shadow, you will need to draw it yourself. Additionally, the window warp can be removed (and shadow restored) by calling CGSSetWindowWarp() with 0, 0, and NULL.

Update: My ironcoder entry is now available, in case you want another example of CGSSetWindowWarp().