Original URL: http://www.theregister.co.uk/2008/07/17/cocoa_frame_two/

Leopard pimpin' method madness

Surf the information super hierarchy

By Dave Jewell

Posted in Developer, 17th July 2008 18:02 GMT

Mac secrets Having dipped into the undocumented frame class used by NSWindow to handle the parts of a window not directly under the control of the application program, its time to go further. Let's dig into the methods exposed by the frame class hierarchy.

The hierarchy of undocumented classes will become obvious if you checked out the source code for last month's project, especially the header files.

At the lowest level, NSFrameView is a direct descendant of NSView. Amongst other things, NSFrameView defines the instance variables for the aforementioned close, zoom and minimize buttons. It also takes care of managing the _titleCell (actually, an instance of NSTextFieldCell) that implements a window's caption.

You might think that by simply sub-classing the frame class (NSThemeFrame, as I demonstrated last time) it should be possible to directly access the titleCell variable and, for example, change the colour of the displayed text in a caption bar. In fact this won't work; the color used for the caption bar text is supplied "on the fly" by another routine with the method signature _drawTitleStringIn:withColor:.

You can see how to exploit this method from a custom frame class below:

- (void) _drawTitleStringIn: (NSRect) rect withColor: (NSColor *) color
        [super _drawTitleStringIn: rect withColor: [NSColor redColor]];

As you'd expect, this will give you a bright red window title: definitely not something you'd ordinarily want to do, except when displaying an "Are you sure you want to reformat the universe?" dialog box.

Although changing the text color of the caption bar's title cell isn't easy unless you're using the method above, it is relatively straightforward to change the background color of the caption text. Simply set up the titleCell instance variable from inside the initializer of your custom frame class like this:

- (id) initWithFrame: (NSRect) frame styleMask: (unsigned) style owner:(id) owner
        self = [super initWithFrame: frame styleMask: style owner: owner];
        if (self)
                NSTextFieldCell * cell = [self titleCell];
                [cell setBackgroundColor: [NSColor yellowColor]];
                [cell setDrawsBackground: YES];
        return self;

The NSTitledFrame class inherits from NSFrameView and NSThemeFrame inherits from NSTitledFrame. If you want to do other unspeakable things to the caption bar, then check out two other routines that are implemented by these classes: titlebarRect returns an NSRect, which corresponds to the entire area of the caption bar, and _titlebarTitleRect, which returns an NSRect that just covers the window title itself.

Window with extra shadow

Demo app sporting a little extra shadow

Another interesting aspect of the frame classes hierarchy is the code that handles the shadow effects associated with a window. The "official" API control you have here is pretty minimalist: you can use the setHasShadow: method to determine whether or not your window has a shadow, and that's about it.

However, you'll notice that NSFrameView implements a method called _shadowType, which returns a bit-mask; effectively, an integer between 0 and 31. Leopard uses subtly different shadowing effects depending whether the window is a utility window, a sheet, or a normal window, whether it is opaque, is the key window, and so on.

What if you want your app to really, er, stand out from the crowd? Do you remember some earlier betas of Leopard? One release had a much more forceful looking window shadow than currently used. If you want to experiment with this, sub-classing the window frame is, once again, the only way to travel. Take a look at the following code:

- (void) _setShadowParameters
        extern OSStatus CGSSetWindowShadowAndRimParameters (void * cid, int wid, 
                  float standardDeviation, float density, 
                  int offsetX, int offsetY, unsigned int flags);
        int stype;
        if ((stype = [self _shadowType]) != [self shadowState])
                [self setShadowState: stype];
                CGSSetWindowShadowAndRimParameters ([NSApp contextID], 
                                           [_window windowNumber], 
                                           35.0, 0.75, 0, 28, 0);

The _setShadowParameters method is called, as needed, to set the shadow parameters associated with the window. Normally, this method looks at the type of window and sets the appropriate type of shadow. Here, we've overridden that behaviour and used the undocumented GSSetWindowShadowAndRimParameters routine to give the window a much more imposing screen presence!

You'll find that it's possible to push the standardDeviation and density values quite a bit higher than I've done, but don't go mad or you'll get unpleasant boundary effects appearing. You have been warned!

As ever, you can download the demo application and source code here