Original URL: http://www.theregister.co.uk/2008/06/19/cocoa_frame/

New vistas with windows frames

Open your mind

By Dave Jewell

Posted in Developer, 19th June 2008 05:02 GMT

Mac Secrets Time to look at the mysterious 'borderView' object, used by the Cocoa libraries to render a window to the screen. Although you'll not often need the specialised facilities provided by the border view, they can be very useful when creating certain kinds of application.

Here's a little experiment you can try. In xCode, create a new, windowed Cocoa application and then add a subclass of NSWindow. You can call this subclass anything you like, but I called mine MyAppWindow. Now go into Interface Builder and change the class of the application window to match. Finally, go into MyAppWindow.m, add an awakeFromNib method, and put the following code inside it:

 

NSLog ([[self _borderView] className]);

When you build the application, the compiler will whinge that the window might not respond to the _borderView selector. If you want to shut the compiler up, check out how I do it by downloading the sample application, at the end. When you run the app, you should see the string NSThemeFrame displayed on the Console. So, what is the border view, and why should you care?

Cocoa programmers are generally only concerned with the content area of a window, and ordinarily, this is the only part of the window they have direct control over. However, the minimize, maximize and close buttons, together with the whole title-bar area are also part of the window, as are the bottom left- and right-hand corners.

All this stuff is handled by a specialised hierarchy of NSView descendents, of which NSThemeFrame is the most commonly encountered. The undocumented _borderView selector returns an instance of this class, which is referred to as a border view or frame view.

Work with handlers

So what can we do with it? If you look at the methods associated with NSThemeFrame, you'll see a couple called setIsClosable: and setIsResizable:. As the name suggests, you can use these methods to control whether or not the window shows a close button, or can be resized. To show this functionality, I added a couple of checkboxes to this month's demo program at the end, and hooked them up to these action handlers:

 

- (IBAction) toggleClosable: (id) sender
{
        [[self _borderView] setIsClosable: [sender state]];
}

- (IBAction) toggleSizable: (id) sender
{
        [[self _borderView] setIsResizable: [sender state]];
}

Ordinarily, you control whether a window can be closed or resized when creating the window, but in exceptional circumstances, you might want to programmatically change these attributes on the fly. (Hint: think of the Karelia Media Browser, and how the window "flips" over. You might want one side of your window to be resizable, and the other not).

Accessing these frame view methods makes this dead easy.

In the same vein, there's another method, _setUtilityWindow: that will enable you to turn a regular window into a utility window, or vice versa. Frankly, I can't see why you would ever want to do this, and it would confuse the hell out of the user, so this one's best avoided!

Cocoa window with padlock

The lock of love: work with showsLockButton

Although not strictly part of the frame view functionality, another useful trick is to be able to display the little "padlock" icon in the top-right corner of a window, just like Safari does when accessing a secure site. I've seen several Cocoa developers ponder how to do this on the web. The NSWindow class implements an undocumented method called showsLockButton. If this method returns YES, then a lock icon will be displayed.

In order to change the state of this on the fly, though, you'll need to "nudge" the frame view object to let it know that the buttons should be updated. This is accomplished as below:

 


[[self _borderView] _updateButtons];

If you want to know when the lock button was clicked, add a lockButtonClicked: method to your window class. It would be nice if you could easily customise the lock button's icon for other purposes, but that's beyond the scope of this article.

To access the real power of what's available here, we need to create our own custom subclass NSThemeFrame, and associate it with the application window. We do this by providing a special method on the window class, frameViewClassForStyleMask, which returns the custom frame view class we want to use. This method is called periodically by the guts of the NSWindow code whenever it needs to access the window's frame view - usually to establish geometry.

Next month, I'll be looking in more detail at what can be done through the provision of a custom border view. Until then, take a look see at how easy it is to drastically alter the appearance of a window simply by overriding the contentAlpha and contentFill methods. You can download the demo application and source code, mentioned earlier, here