Every application has a central object named NSApp , which is an instance of the NSApplication class. At the core of its responsibilities is the management of the run loop . A run loop monitors the various sources of events and decides which object is responsible for handling each event. It then sends a message, passing to the object an NSEvent object instance to describe the particulars of the event. The event message passes from NSApp to the appropriate window, to a view (commonly a control) within the window, and eventually to the target object.

This is how a button “knows” that it has been clicked. The application forwards mouse click events to it. The button object can then either process the event directly or, more commonly, pass it on to a custom object that you define through the target/action pattern or delegation. When the handling objects are finished responding to the message, control unwinds and returns to NSApp, where the run loop processes the next event.

This cycle, also known as the event cycle, usually starts at launch time when the application sends a stream of Quartz commands to the window server for it to draw the application interface. The application then begins its main run loop and begins accepting input from the user. When users click or drag the mouse or type on the keyboard, the window server detects and processes these actions, passing them to the application as events.

Events sent to the application by the window server are placed on a queue in the order they are received. On each cycle of the run loop, NSApp processes the topmost event in the queue, as shown in Figure 8-2. When NSApp finishes processing the event, it gets the next event from the queue and repeats the process again and again until the application terminates.

Figure 8-2. The event queue

Recall that when we introduced the core program framework of NSWindow, NSView, and NSApplication in Chapter 6, we mentioned that each of these classes inherits functionality from the NSResponder class, as shown in Figure 8-3.

Figure 8-3. The core application framework

The NSResponder class defines the default message-handling behavior of all event-handling objects in an application. The responder model is built around the following three concepts:

Responder chains allow responder objects to delegate responsibility to other objects in the system. The series in a responder chain is determined by the interrelationships between the application’s view, window, and its NSApp object. For a view, the next responder is usually its superview. The next responder of a window’s content view is the window itself. From there, the event is passed to the NSApp object.

For action messages, the responder chain is longer. Messages are first passed up the responder chain to the window. Then, if the previous sequence occurred in the key window, the same path is followed for the main window. After that, the message is passed to the NSApp object.

Each window in an application keeps track of the object in its view hierarchy with first responder status, which is the view that first responds to keyboard events for that window. For example, in TextEdit, the new document window is the first responder, as it is the first to receive events from the keyboard. By default, a window is its own first responder, but any view within the window can become the first responder when the user clicks it with the mouse. If the view cannot handle the event, the event is passed on to the next object in the responder chain.

In a desktop environment where multiple windows can be open at any given time, a user selects a window with the mouse to make it active. When this happens, that window becomes key, and the window’s first responder becomes the target of any events generated by the user. If a different window is selected, it becomes key, and its first responder becomes current. If no object has been selected, or if the window has no controls, the window is its own first responder.

Using Interface Builder, or programmatically, you can configure an initialFirstResponder so that when a window appears, the first logical control capable of using keystrokes is brought into focus as the first responder. Recall that in Chapter 5’s Currency Converter application, we set the first text field to be the initial first responder.

Views and controls can reject first responder status. For example, a view displaying a static image probably shouldn’t accept first responder status. A responder can indicate that it doesn’t want to accept first responder status by implementing the acceptFirstResponder method and returning NO.

An event is routed based on its type. The NSApp object sends most event messages to the window in which the user action occurred. A mouse event is then forwarded to the view in the window’s view hierarchy within which the mouse was clicked. Key events are routed to the first responder. If the view can respond to the event—that is, if it can accept first responder status and define an NSResponder method corresponding to the event message—it handles the event. If the view cannot handle an event, the event is forwarded to the next responder in the responder chain.

The NSWindow class handles some events itself, such as window-moved, window-resized, and window-exposed events, and doesn’t forward them to a view. NSApp also processes a few events, such as application-activate and application-deactivate events.

Creating the functionality of this application will utilize many of the same skills presented in previous chapters. We will start shortening the descriptions of how to perform tasks that we’ve performed before so that we can provide more details on new topics as they are introduced. If you can’t remember how to do something, you should use the procedures presented in previous chapters to help you out. Create the DotView class using the following steps:

To create our interface, perform the following steps:

Figure 8-5. The Dot View user interface

Create the following connections using Interface Builder.

Save (

-S) the nib file, and return to Project Builder, where we will finish the application.

Our next step is to finish defining the DotView.h header file. Edit the source to match that of Example 8-1. The code that you need to add to the Interface Builder code is shown in boldface.

/* DotView */

#import <Cocoa/Cocoa.h>

@interface DotView : NSView
{
    IBOutlet NSColorWell * colorWell;
    IBOutlet NSSlider * slider;

    NSPoint center;                                                        // 1
    NSColor * color;                                                       // 2
    float radius;                                                          // 3
}
- (IBAction)setColor:(id)sender;
- (IBAction)setRadius:(id)sender;

@end

This code defines the following functionality:

Now that we have defined the header, it’s time to add the code for the implementation of the DotView class. The code for this class is too long to fit nicely on one page, so we’re going to approach this in two steps. First, Example 8-2 shows the skeleton of our class, with all the methods to implement shown in boldface. As you can see, you will be asked to insert code from later examples as we build the Dot View application. The sections that follow will provide the necessary code, along with explanations of what that code will do.

First, enter the boldface text from Example 8-2 into your DotView.m file, and insert the appropriate code from Example 8-3 through Example 8-10 as you work through the following sections. A complete version of how your DotView.m file should look is shown in Example 8-11.

#import "DotView.h"

@implementation DotView

- (id)initWithFrame:(NSRect)frame 
{
                     // Insert code from Example 8-3
                     }

- (void)awakeFromNib
{
// Insert code from Example 8-4
                     }

- (void)dealloc
{
                     // Insert code from Example 8-5
                     }

- (void)drawRect:(NSRect)rect
{
                     // Insert code from Example 8-6
                     }

- (BOOL)isOpaque
{
                     // Insert code from Example 8-7
                     }

- (void)mouseDown:(NSEvent *)event
{
                     // Insert code from Example 8-8
                     }

- (IBAction)setColor:(id)sender
{
                     // Insert code from Example 8-9
                     }

- (IBAction)setRadius:(id)sender
{
                     // Insert code from Example 8-10
                     }

@end

- (id)initWithFrame:(NSRect)frame
{
    self = [super initWithFrame:frame];                                    // 1
    center.x = 50.0;                                                       // 2
    center.y = 50.0;                                                       // 3
    radius = 20.0;                                                         // 4
    color = [[NSColor redColor] retain];                                   // 5
    return self;                                                           // 6
}

- (void)awakeFromNib
{
    [colorWell setColor:color];                                            // 1
    [slider setFloatValue:radius];                                         // 2
}

- (void)dealloc
{
    [color release];                                                       // 1
    [super dealloc];                                                       // 2
}

- (void)drawRect:(NSRect)rect
{
    NSRect dotRect;                                                        // 1

    // Draw the background
    [[NSColor whiteColor] set];                                            // 2
    NSRectFill([self bounds]);                                     

    // Set the location of the dot
    dotRect.origin.x = center.x - radius;                                  // 3
    dotRect.origin.y = center.y - radius;                   

    // Define the size the dot
    dotRect.size.width = 2 * radius;                                       // 4
    dotRect.size.height = 2 * radius;                              

    // Set the default color
    [color set];                                                           // 5

    // Draw the dot
    [[NSBezierPath bezierPathWithOvalInRect:dotRect] fill];                // 6
    
}

- (BOOL)isOpaque
{
    return YES;
}

- (void)mouseDown:(NSEvent *)event
{
    NSPoint eventLocation = [event locationInWindow];                      // 1
    center = [self convertPoint:eventLocation fromView:nil];               // 2
    [self setNeedsDisplay:YES];                                            // 3
}

- (IBAction)setColor:(id)sender
{
    NSColor * newColor = [sender color];                                   // 1
    [newColor retain];                                                     // 2
    [color release];                                                       // 3
    color = newColor;                                                      // 4
    [self setNeedsDisplay:YES];                                            // 5
}

Implement the setRadius: action method

This method is called by the slider whenever the user moves the slider left or right to change the size of the dot. This method assumes that the send is a control capable of returning a floating-point number. Edit the setRadius: method as shown in Example 8-10.

Example 8-10. Changing the size of our dot

- (IBAction)setRadius:(id)sender
{
    radius = [sender floatValue];                                          // 1
    [self setNeedsDisplay:YES];                                            // 2
}

This code performs the following tasks:

1. Sets the radius variable to a float value (floatValue) obtained from the slider.

2. Sets a flag indicating that the view needs to be redrawn to display the newly resized dot, based on the movement of the slider. The redraw will be done automatically by the AppKit after the event is handled.

When you’ve completed entering all of the code from Example 8-2 through Example 8-10, your DotView.m file should look like the code shown in Example 8-11.

Example 8-11. The complete DotView.m file

#import "DotView.h"

@implementation DotView

- (id)initWithFrame:(NSRect)frame 
{
    self = [super initWithFrame:frame];
    center.x = 50.0;
    center.y = 50.0;
    radius = 20.0;
    color = [[NSColor redColor] retain];
    return self;
}

- (void)awakeFromNib
{
    [colorWell setColor:color];
    [slider setFloatValue:radius];
}

- (void)dealloc
{
    [color release];
    [super dealloc];
}

- (void)drawRect:(NSRect)rect
{
    NSRect dotRect;

    [[NSColor whiteColor] set];
    NSRectFill([self bounds]);

    dotRect.origin.x = center.x - radius;
    dotRect.origin.y = center.y - radius; 

    dotRect.size.width = 2 * radius;
    dotRect.size.height = 2 * radius; 

    [color set];

    [[NSBezierPath bezierPathWithOvalInRect:dotRect] fill];
}

- (BOOL)isOpaque
{
    return YES;
}

- (void)mouseDown:(NSEvent *)event
{
    NSPoint eventLocation = [event locationInWindow];
    center = [self convertPoint:eventLocation fromView:nil];
    [self setNeedsDisplay:YES];
}

- (IBAction)setColor:(id)sender
{
    NSColor * newColor = [sender color];
    [newColor retain];
    [color release];
    color = newColor;
    [self setNeedsDisplay:YES];
}

- (IBAction)setRadius:(id)sender
{
    radius = [sender floatValue];
    [self setNeedsDisplay:YES];
}

@end

Once your DotView.m file is complete, save the project (File → Save, or

-S), and then build and run the Dot View application (Build → Build and Run, or

-R). You should see something that looks like Figure 8-6.

Figure 8-6. Drawing dots with the Dot View application

Perform the following actions on the application to see if the code that we added works:

• Click anywhere in the view, and you’ll see the dot move to the point that you clicked. Each time you click the mouse, a mouseDown event is sent to the view, resulting in the mouseDown: method being called.

• Move the slider left and right, and watch the size of the dot get smaller or bigger, respectively. Notice that the slider issues events to the application as it moves, allowing you to see the results of the action dynamically.

• Click on the color well, and pick a new color for the dot from the palette that appears. Just like the slider, the color well responds dynamically.

Note that when you resize the application, the view doesn’t autosize as we’d probably like. Exercise 6 at the end of this chapter (Section 8.5) adds this functionality.

Open the Dot View project in Project Builder, if you don’t already have it open, and open the MainMenu.nib file in Interface Builder. Perform the following steps to create a delegate class and to assign an instance of it as a delegate to the window:

Figure 8-8. Control-dragging from Window to MyDelegate

Return to Project Builder, and edit MyDelegate.m to match the code in Example 8-12.

#import "MyDelegate.h"

@implementation MyDelegate

- (BOOL)windowShouldClose:(NSWindow *)sender                              // 1
{
    int answer = NSRunAlertPanel(@"Close", @"Are you certain?",           // 2
                                 @"Close", @"Cancel", nil);
    switch (answer) {                                                     // 3
        case NSAlertDefaultReturn:
            return YES;
        default:
            return NO;
    }
}

@end

The code we added performs the following tasks:

Now save the project (

-S), and build and run the application (

-R). When you try to close the application window, you will see something that looks like Figure 8-9. Notice what happens when you hit the Cancel button on the alert box. Notice that the alert only comes up when you close the window. If you quit the application, the alert panel will not appear. A different delegate method, the applicationShouldTerminate: method of the NSApplication class, is needed to enable this functionality. Exercise 4 at the end of the chapter (Section 8.5) will do so.

Figure 8-9. Dot View asking permission to close

Another example of delegation appears in the implementation of Aqua’s sheets—a new type of dialog box that is attached to a document window’s titlebar. Sheets slide out from the window title, making their relationship to a document clear. Sheets are modal only for the window to which they are attached, so you can proceed to other tasks in an application before dismissing them.

Adding support for sheets is more complicated than using a standard dialog box, because the function that displays an alert sheet—NSBeginAlertSheet — is asynchronous. In other words, it does not wait for the user to dismiss the sheet before returning control to the caller. Instead, it returns control immediately after presenting the sheet. To discover the result of the user’s interaction with the sheet, you must pass a reference to a delegate object, along with a method selector to invoke as a callback when the sheet is dismissed. When the sheet finished, the callback method will be invoked and passed a result code, indicating which button the user pressed.

The NSBeginAlertSheet function has the following signature:

void NSBeginAlertSheet(NSString * title, 
                       NSString * defaultButtonLabel, 
                       NSString * alternateButtonLabel,
                       NSString * otherButtonLabel, 
                       NSWindow * docWindow, 
                       id modalDelegate, 
                       SEL didEndSelector, 
                       SEL didDismissSelector, 
                       void * contextInfo, 
                       NSString * message, 
                       ...)                         // printf args for message

This looks a bit daunting at first, but it’s really not as difficult to use as it might look. Table 8-2 provides a brief parameter summary for NSBeginAlertSheet.

title

defaultButton

alternateButton

otherButton

docWindow

modalDelegate

didEndSelector

didDismissSelector

contextInfo

msg

Edit the MyDelegate.m code, replacing the windowShouldClose: method and adding the sheetClosed: method, as shown in Example 8-13.

#import "MyDelegate.h"

@implementation MyDelegate

- (BOOL)windowShouldClose:(NSWindow *)sender
{
    NSString * msg = @"Should this window close?";                        // 1
    SEL sel = @selector(sheetClosed:returnCode:contextInfo:);             // 2

    NSBeginAlertSheet(@"Close",       // title                            // 3
                      @"OK",          // default label
                      @"Cancel",      // alternate button label
                      nil,            // other button label
                      sender,         // document window
                      self,           // modal delegate
                      sel,            // selector to method
                      NULL,           // dismiss selector
                      sender,         // context info
                      msg,            // message
                      nil);           // params for msg string
    return NO;                                                            // 4
    
}

- (void)sheetClosed:(NSWindow *)sheet
         returnCode:(int)returnCode
        contextInfo:(void *)contextInfo
{
    if (returnCode == NSAlertDefaultReturn) {                             // 5
        [(NSWindow *)contextInfo close];
    }
}

@end

This code performs the following tasks:

Save the project (

-S), and then build and run the application (

-R). Now when you try to close the window (

-W), you should see something like Figure 8-10.

Figure 8-10. Aqua sheets in action

A class that posts notifications defines the names of those notifications in its header file as static NSString objects. For example, the NSWindow class defines a set of 16 notifications in its header file that allow other objects to monitor changes in the window’s status:

APPKIT_EXTERN NSString * NSWindowDidBecomeKeyNotification;
APPKIT_EXTERN NSString * NSWindowDidBecomeMainNotification;
APPKIT_EXTERN NSString * NSWindowDidChangeScreenNotification;
APPKIT_EXTERN NSString * NSWindowDidDeminiaturizeNotification;
APPKIT_EXTERN NSString * NSWindowDidExposeNotification;
APPKIT_EXTERN NSString * NSWindowDidMiniaturizeNotification;
APPKIT_EXTERN NSString * NSWindowDidMoveNotification;
APPKIT_EXTERN NSString * NSWindowDidResignKeyNotification;
APPKIT_EXTERN NSString * NSWindowDidResignMainNotification;
APPKIT_EXTERN NSString * NSWindowDidResizeNotification;
APPKIT_EXTERN NSString * NSWindowDidUpdateNotification;
APPKIT_EXTERN NSString * NSWindowWillCloseNotification;
APPKIT_EXTERN NSString * NSWindowWillMiniaturizeNotification;
APPKIT_EXTERN NSString * NSWindowWillMoveNotification;
APPKIT_EXTERN NSString * NSWindowWillBeginSheetNotification;
APPKIT_EXTERN NSString * NSWindowDidEndSheetNotification;

An object that wants to receive one of these notifications must use the notification name when registering with the notification center.

To show how to work with notifications, we will add some functionality to our Dot View application delegate to listen to notifications that NSWindow generates when sheets are used. Edit the MyDelegate.m file, adding the code shown in Example 8-14. The order of methods in a source-code file doesn’t matter; however, you usually see init methods towards the top of a class implementation.

                     - (id)init                                                                    
{
    NSNotificationCenter * center = [NSNotificationCenter defaultCenter];   // 1
    [center addObserver:self                                                // 2
               selector:@selector(sheetDidBegin:) 
                   name:NSWindowWillBeginSheetNotification
                 object:nil];
    return self;
}

- (void)sheetDidBegin:(NSNotification *)notification
{
    NSLog(@"Notification: %@", [notification name]);                        // 3
}

The code that we added performs the following functionality:

Save the project (

-S), and then build and run the application (

-R). When you run Dot View and try to close the window, the sheet will appear with the following message in the console pane of Project Builder:

2002-04-01 12:07:47.837 Dot View[800] Notification: NSWindowWillBeginSheetNotification

Obviously, you wouldn’t display notifications like this to users of your applications. Rather, you would use them inside your application to coordinate various activities.

Notification centers do not retain observer objects, so you should be careful to remove any observers before they are deallocated. This is to prevent the notification center from sending a message to an object that no longer exists. MyDelegate registers itself as an observer in its init method, so the object should remove itself in its dealloc method. Add the dealloc method implementation to MyDelegate.m, as shown in Example 8-15.

- (void)dealloc
{
    [[NSNotificationCenter defaultCenter] removeObserver:self];
    [super dealloc];
}

If an object registers another object with the notification center without releasing it after removing it from the notification center, the application will leak memory. Therefore, any object that registers itself, or another object, with the notification center should remove itself or the registered object from the notification center before it is deallocated.