KATI

Hello!!

Thanks for all of the feedback on the XS-Controllers design that Jonathan and I posted. We’re going to be making some changes to the design based on feedback, bug reports and the experience we’ve had using it ourselves over the past few months.

First, I want to take a few steps back and offer a couple of example projects that use NSViewController – straight out of the box - in a non-document based application. I hope these will be more useful for people who are just starting out with view controllers. The projects do the following:

Create a view controller with a nib file

Add several view controllers’ views to the window’s view hierarchy

Switching between two view controllers and their views

Patch a single view controller into the Responder Chain

There’s also a good sample project available on Apple’s site. I recommend checking it out.

Simple View Controller Xcode Projects

Simple View Controller - Adding Views to the View Hierarchy

Download SimpleViewControllerPart1.zip

A window controller creates two view controllers and
adds their views to the window’s view hierarchy. The window controller keeps references to the view controllers as instance variables. They are not added to the responder chain.

Simple View Controller 2 - Switching View Controllers

Download SimpleViewControllerPart2.zip

This project extends the previous project so that the DetailViewController manages the switching between two other view controllers and adding their views to its “contentView”. This gives you tab-like behavior with the addition of view controller switching instead of just view switching.

The DetailViewController is patched into the responder chain when it is created, after its view is added to the window, so that it can handle the View menu actions for switching the views.

Note on the Responder Chain:

If you take a look at the sample code, you’ll notice that I added the DetailViewController to the responder chain after the window controller. This follows Jonathan’s and my design for the XSViewControllers. Many people have asked why we didn’t add the XSViewControllers into the responder chain after their associated views instead. There a couple of reasons for this:

A view controller can’t control when its view is added and removed from the view hierarchy, so in a design like ours, there is no reliable way to patch the chain in this way without subclassing and extending NSView to be aware of its view controllers. This is a more intrusive design, in my opinion.

There is a significant behavior difference between the two approaches. Action messages take a specific route through the responder chain. In order for a view controller to be able to validate a menu item, its view or one of its subviews will need to be the first responder. This means that you have to subclass the view, override ‘acceptsFirstResponder’ to return “YES” – AND that your user has to click in the view before going to the menu in order for the menu items to be usable.

Placing the view controllers in the same part of the chain as the other controller classes ensures that the action message can travel to them, regardless of which view is the first responder. The controllers can then decide which items to validate based on their own internal logic.

To see the difference in behavior of the two approaches, change the sample code from the SimpleViewController2 project in the file MainWindowController.m, in the windowDidLoad: method:

	// patch the detail view into the responder chain
	NSResponder * aNextResponder = [self nextResponder];
	[self setNextResponder:mDetailViewController];
	[mDetailViewController setNextResponder:aNextResponder];

to

	// patch the detail view into the responder chain
	NSResponder * aNextResponder = [aDetailView nextResponder];
	[aDetailView setNextResponder:mDetailViewController];
	[mDetailViewController setNextResponder:aNextResponder];

After you make that change, build and run the project. Click within the detail view area to make it the window’s First Responder. Go to the ‘View’ menu and the items will be validated. Now click into the table view area and then return to the ‘View’ menu. The menu items won’t be validated. You will have to click in the detail view area again to validate the menu items. This isn’t the desired behavior for these menu items.

Anyway…

NSViewController and IB

NSViewController is designed to be used with a nib file. As you can with NSWindowController, you will initialize a view controller with the name of its associated nib file.

mTableViewController = [[TableViewController alloc] initWithNibName:@"TableView" bundle:nil];

The view controller will automatically load the nib when it is asked to return its view for the first time. In order for all of this to go smoothly, there are two things to be sure to do in your nib file:

1. Set the File’s Owner’s “Class” to be the NSViewController subclass that will be managing its view

1. Drag the view controller’s header file into the IB project or use the “Read Class Files…” command in the File menu and select the header file.
2. Select the “File’s Owner” object and go to “Identity” tab in the inspector palette. Start typing the class name of the view controller. It should autocomplete for you.

2. Connect the File’s Owner’s (your view controller) “view” outlet to the nib’s top level view.

1. Ctrl-drag from “File’s Owner” to the view.
2. Select the “view” outlet when the small context menu pops up.

That’s it!

Resources

NSViewController Class Reference

Apple’s View Controller Sample Code (shows example of switching view controllers)

NSResponder Class Reference

The Responder Chain for Action Messages (from the docs on the Event Architecture)

In the last post on NSViewController, I described the need for a view controller class that is part of a sound controller architecture, especially when developing an application with a single window interface. In this post, Jonathan Dann and I will share the design we came up with for integrating NSViewController into the existing Cocoa MVC application architecture using NSWindowController as the glue.

Before, we do that…

Meet Jonathan.

I’m currently training with the National Health Service in the UK, working towards becoming a state-registered Medical Physicist. I was introduced to programming during my Bachelor’s degree where I did a short course in C. During my Master’s degree I learnt some FORTRAN and then had my first experience of object-oriented programming during that year. Since then I’ve been learning as much as I could about Cocoa, design patterns, and the whole world of Mac programming. I’ve begun to write my first app, which will be available sometime around September, which really began life as a personal project when the tool I was using didn’t work right and didn’t fit properly within OS X.

As my code grew in size I soon realised that I needed a controller for some of my more complex view behaviour, NSSplitViews, NSTextViews, NSOutlineViews all need delegates to unlock their power and when all of this was in the same window controller I got the feeling it was doing work that it shouldn’t have to. I started using NSViewController and came to the conclusion that it didn’t quite fit in my design, after considering how MVC should work I asked on cocoa-dev how other people use it. Sure enough, it sparked some conversation. I think that Apple has left the use of this class up to developers intentionally, maybe they will extend it in future releases, maybe having a structured controller system seems a little abstract for smaller programs, but I think it makes things easier to maintain in the long-run.

After using the class for a while I am of the mind that each view in an app could potentially have its own controller, although this would probably be overkill; the only structure that then makes sense is a tree, just like the view hierarchy. I now use these classes extensively to inform the views, for example, how they should look: the view can then draw itself based on those options it gets from its overlord.

The XS (extra special) Controllers

Our solution includes to two classes:

1. XSWindowController, an NSWindowController subclass
2. XSViewController, an NSViewController subclass

You can find these classes in the example project (XCode 3.0). Dowonload it here.

The Goal of This Design

The goal of our design is simple: We want a way to manage a group of view controllers in a way that fits in nicely with the current Cocoa MVC architecture.

When building a Cocoa app, the controller layer of the architecture can be described very loosely as:

• NSDocument contains a list of NSWindowControllers
• Each window controller has an associated window

We want to extend this design so that:

• NSDocument contains a list of NSWindowControllers*
• Each NSWindowController conains a list of NSViewControllers
• Each NSViewController contains a list of subcontrollers
• Each NSViewController has an associated view

*Our changes happen beneath the document layer, so it is also a valid design for applications that aren’t document-based.

XSViewController and XSWindowController

In order to meet our goals, we enhanced Cocoa’s NSWindowController and NSViewController classes.

In XSViewController, we added a list of subcontrollers and the necessary methods to manage that list. We also gave the view controllers a reference to the window controller.

In XSWindowController, we added a list of view controllers. The window controller is the “host” for the view controllers, so when the window controller is created and destroyed by the document, it does the same to the view controllers. The window controller also does some extra work that is necessary for the view controllers to be integrated smoothly into the existing Cocoa controller architecture. We’ll describe this work further down.

In this setup, you would use the following XSWindowController methods to add and remove view controllers,

- (void)addViewController:(XSViewController *)viewController;
- (void)removeViewController:(XSViewController *)viewController;

In XSViewController, you can nest controllers and manipulate the structure of the controller tree using several methods that will be familiar to those who have worked with mutable arrays,

- (void)addChild:(XSViewController *)child;
- (void)insertObject:(XSViewController *)child inChildrenAtIndex:(NSUInteger)index;
- (void)insertObjects:(NSArray *)children inChildrenAtIndexes:(NSIndexSet *)indexes;
- (void)insertObjects:(NSArray *)children inChildrenAtIndex:(NSUInteger)index;
- (void)removeChild:(XSViewController *)child;
- (void)removeObjectFromChildrenAtIndex:(NSUInteger)index;

As long as you use these methods to add and remove view controllers from the application, you will get all of the benefits of the design.

Quick design note:

We want to note here that we considered a design where the window controller contained one view controller that would be the root of a single view controller tree. We chose to keep a list of view controllers in the window controller because it feels redundant to have to make a second controller that represents the entire window.

In a perfect world, the view controllers and window controllers would actually be the same class, so that the window controller would be the root of a single tree of controllers. This isn’t possible, but we decided that we would design with that structure in mind anyway.

Working with Cocoa

So, after we had this system set up and running, making sure that memory management was handled properly, we had to handle some Cocoa-specific behaviors so that the view controllers were well integrated into the Cocoa application architecture. This is the “glue-code” of this design. There are two Cocoa-related issues that we had to consider.

Cocoa Consideration 1: Taking care of the Responder Chain

NSViewController is a subclass of NSResponder, but it needs to be added to the responder chain to receive action events from things like buttons and menu items. We decided that our design should patch the responder chain so that it runs through the view controllers like this:

We looked at two approaches to solving this problem. The first approach would be to handle the responder chain in the NSViewController class, so that when a view controller was added or removed from the tree, its super controller would make sure the responder chain was patched together correctly.

The other approach is to have the window controller do the responder chain patching whenever a view controller is added or removed.

Both of these approaches have their advantages and disadvantages.

The first approach would keep things logically clean and less glue-like. The view controllers wouldn’t have to communicate back to the window controller when they add or remove their subcontrollers. If this were the perfect design world, where the window and view controllers were in the same tree, this would be the obvious way to maintain the responder chain throughout a single hierarchy of controllers.

The second approach is just more simple in this particular setup. Since this isn’t the perfect design world, the code that adds the view controllers to the responder chain would have to be repeated in both classes anyway. Letting one class handle the responder chain keeps this code centralized.

We decided to use the second approach. We don’t feel that there is a perfect solution to this problem and that either approach works fine.

The method that patches the responder chain is in XSWindowController:

- (void)patchResponderChain;

The source code will show how simple it is to keep the responder chain looking like it does in the diagram.

Consideration 2: Bindings and Observations

Bindings and Key-Value Observing are powerful Cocoa mechanisms that help us to keep our controllers and our data models separate. Most view controllers and window controllers will have bindings or KVO set up in some way.

In NSViewController, there is the idea of a “representedObject”. According to the documentation of NSViewController:

Declaring a generic representedObject property, to make it easy to establish bindings in the nib to an object that isn’t yet known at nib-loading time or readily available to the code that’s doing the nib loading.

This is a handy feature of NSViewController, especially if you are setting up all of your bindings in Interface Builder, but in a more complex setup, the single “representedObject” may not be the best way to expose a view controller to the data in an application.

There are situations where you might want to set up several KVOs and bindings in code and then remove them when you don’t need them anymore. If you forgo the “representedObject” as a means to set up KVO with your application’s data, you might come across this message in your logs when you close the document:

An instance (so-and-so) of class (so-and-so) is being deallocated while key value observers are still registered with it. Break on _NSKVODeallocateLog to start debugging.

We decided to go ahead and handle the possibility of these situations by adding a method to XSViewController called,

- (void)removeObservations;

This gives the view controllers a chance to remove observations or bindings that they set up in code before the data is released. The window controller has to manage the timing of this. In XSWindowController, we do it right before the window closes, in an implementation of the window’s delegate method,

- (void)windowWillClose:(NSNotification *)notification;

The window controller tells its view controllers to “removeObservations” here and they pass the message on to their subcontrollers. The window controller and document can then release data as they normally would in their implementations of “dealloc”.

Quick notes on subclassing:

If an XSViewController subclass implements the “removeObservations” method, it is responsible for calling super’s implementation so that the message will continue to be propagated down its branch of the tree.

If an XSWindowController subclass needs to implement “windowWillClose”, it should be sure to call super’s implementation so that the view controllers will get the message to remove their observations. The timing of this message is important, so if you are releasing some data here, be sure to call super first.

Using “windowWillClose” for a feature like this may not be the best solution, but as far as we can tell, it seems like the most convenient place to perform this task.

That’s It.

With these few enhancements, we now have two new abstract super-classes for our controllers, XSWindowController and XSViewController. When we subclass them to build our UIs, we get the controller architecture that we illustrated at the beginning of the post and the following features built in to our view controller:

• Automatic memory management!
• Automatic inclusion in the responder chain!!!
• A designated method for removing observations or bindings!
• A relationship with the window controller and document!

This design will become more and more useful as your single window interface becomes more complex, especially as your feature set changes over the life-time of your development. With this architecture in place, you have more flexibility to try things out and change your design without worrying about breaking the responder chain (which is not that easy to debug) or causing memory leaks by accident as you’re working rapidly to test UI designs. As long as you keep to MVC design principles, it is possible to create self-contained view controllers that can be plugged in to, and unplugged from, your UI with very little hassle.

Next Time…

First, thanks so much to Jonathan for working on this post with me. It was great to have the chance to brainstorm with another developer, especially one whose applications are completely different from the ones I work on every day. Working with him on this design helped to get me out of my usual mind-set and to isolate the issues that are truly common to any Cocoa application rather than unique to my own projects. This has been an educational and super-productive experience for me – Thanks, Jonathan!

AND a another big thanks to Jonathan for setting up the Xcode 3.0 example project and the source code!

In the next and last post about NSViewController, I’m going to discuss its relationship to NSView and the view hierarchy in more detail. One of the many important jobs of a view controller is to help to build and manage the view hierarchy during runtime. This is especially important when coding a single window interface that needs to give users access to many different features that can’t all be displayed in the window at one time.

Anyone who is sick of me writing about autoresizing should just skip the next installment ; ) ( or in Japanese, ^_- )

Resources

The example project contains XSWindowController and XSViewController, which contain all the nitty-gritty implementation details. There is also an example app that shows how you could subclass these classes to build a UI based on the XS controllers.

Cocoa Event-Handling Guide: The Responder Chain

Introduction to Document-Based Applications Overview

NSViewController Class Reference

NSWindowController Class Reference

Introduction to Key-Value Observing Programming Guide

Introduction to Cocoa Bindings Programming Topics

UPDATE 04/23/08

We updated the example project today. The biggest change we made is in XSViewController. We were previously setting the “representedObject” of child controllers to be that of its parent. In the new version we don’t deal with “representedObject” in any way. You can just use NSViewControllers methods to set them case-by-case.

XCode Project

Just the Source Code

Just XSViewController and XSWindowController