Volume Number: 21 (2005)
Issue Number: 7
Column Tag: Programming

Save Our Screens 102

How To Write A Mac OS X Screen Saver, Part 2

by David Hill

Introduction

In the last article, we covered some introductory material and put together a basic screen saver. We also covered some debugging tips that should have helped you get your own projects started. Now that you've got a simple screen saver up and running and you've got a grasp of the ScreenSaverView class, let's take things a bit further and add a simple configuration sheet. We'll need to make several modifications to our project.

1. Change the code in projectNameView.h to this:

   #import <ScreenSaver/ScreenSaver.h>
   #define kConfigSheetNIB @"ConfigureSheet"

   @interface projectNameView : ScreenSaverView {
      IBOutlet NSWindow* configureSheet;
      IBOutlet id shouldRotateCheckbox;
      BOOL isRotatingRectangles;
      BOOL mDrawBackground;
   }
   - (IBAction) cancelSheetAction: (id) sender;
   - (IBAction) okSheetAction: (id) sender;
   @end

2. Change the hasConfigureSheet method to return YES.

3. Change the code in the configureSheet method to this:

if ( configureSheet == nil ) {
      [NSBundle loadNibNamed: kConfigSheetNIB owner: self];
   }
   [shouldRotateCheckbox setState: isRotatingRectangles];
   return configureSheet;

4. Conditionalize the rotation code in drawRect: like so:

   if ( isRotatingRectangles ) {
      NSAffineTransform* rotation =
                  [NSAffineTransform transform];
      float degrees = SSRandomFloatBetween( 0.0, 360.0 );
      [rotation rotateByDegrees: degrees];
      [rotation concat];
   }

5. Add the following line to initWithFrame:isPreview: before returning self:

isRotatingRectangles = YES;

6. Add a cancelSheetAction: method that should look like:

   - (IBAction) cancelSheetAction: (id) sender {
      //  close the sheet without saving the settings
      [NSApp endSheet: configureSheet];
   }

7. Add an okSheetAction: method that should look like:

   - (IBAction) okSheetAction: (id) sender {
      //  record the settings in the configuration sheet
      isRotatingRectangles = [shouldRotateCheckbox state];
      [NSApp endSheet: configureSheet];
   }

That's the easy part to explain since it only involves code. We've got all the code in place for our configuration sheet, but where's the sheet itself? That would be the tricky part. Fire up Interface Builder and create a new empty NIB. In order to connect our screen saver view class to elements in the NIB and vice versa, we're going to need to teach IB about our custom class. By default, IB doesn't know about the ScreenSaverView superclass so we'll start there. Arrange your project window and the NIB window such that you can see both. Open the ScreenSaverView.h header file in Xcode and drag the header (either the window title bar proxy or the header icon in the Groups and Files outline) to the NIB window. You should see a green cursor with a plus in it when the cursor is over the IB window as seen in Figure 1. That's a good sign and it means that IB will parse the file and absorb the ScreenSaverView class information when you drop the header file into the IB window.

Now we're ready to teach IB about our custom projectNameView class but there's a simpler way than dragging header files around and juggling windows. Switch to IB, switch to the Classes tab in the NIB window, and select Read Files... from the Classes menu. In the resulting dialog, navigate to your project folder, select your projectNameView.h header, and click Parse. As a final step, we need to tell IB that our NIB will be owned (this usually means loaded) by our custom class. Switch the NIB file view to Instances and select the File's Owner. Open the Info window (SHIFT-CMD-I) and select Custom Class (CMD-5) from the popup menu. Find projectNameView in the list and select it to change the class.

At this point, IB knows about our custom header file and we can start creating the sheet and wiring it up. The screen saver engine is expecting the configureSheet method to return an NSWindow so let's give it one. Show the palette in IB and select the Windows button from the toolbar. Drag a normal window into the NIB document window to add it to your NIB. Switch to the Controls portion of the IB palette and add a switch (a checkbox for you Carbon people) and two buttons to your window. Change one button to say OK and the other to say Cancel. Change the switch to say something like Rotate the rectangles but the exact title doesn't matter. The window should look something like the one in Figure 2.

With our controls in place, we need to make our final connections. The view needs to know about the sheet in order to close it and the controls need to know how to tell the view they've been clicked. Control-drag from the File's Owner to the window (either in the Instances view or the titlebar of the window itself) and set the configureSheet connection. See Figure 3 if you need help. Control-drag from File's Owner to the checkbox and connect it to the shouldRotateCheckbox outlet. Control-drag from the OK and Cancel buttons to File's Owner and set the okSheetAction: and cancelSheetAction: connections, respectively. Figure 4 shows the okSheetAction: connection.

Now we're getting somewhere. Save this new NIB file as ConfigureSheet into your project directory and IB will ask if you'd like to add it to your currently open Xcode project. Click Add. Build your screen saver and try it out. If we're lucky, the saver will still build and work. Open the Desktop and Screen Saver preferences pane, select your saver, and click the Options button to see your new configuration sheet. Hopefully it looks a lot like Figure 5. Turn the rotation checkbox off then close the sheet and watch what happens to the Preview. Looks good, right? Ah, but there's one small problem. Click the Test button and see for yourself.

Why is the screen saver still rotating rectangles when we clearly turned off the checkbox in the configuration sheet? The answer is simple and this is a good excuse to drive home the underlying reason. The screen saver engine creates a separate instance of the current saver whenever it needs to blank a different area. The Preview pane gets an instance. The Test run of the saver gets a new, separate instance, and if you run the saver for real via a hot corner you'll get yet another instance. Those of you with multiple monitors may have already noticed that the saver draws different things on each monitor which shows that each monitor also gets its own instance of the screen saver. For the most part, this is a good thing but there are times when you'd like to share some state between the different instances. User preferences are the most common case and the ScreenSaver framework provides a convenient solution in the form of the ScreenSaverDefaults class and its defaultsForModuleWithName: method.

In the next section, we'll use defaultsForModuleWithName: to store and retrieve the current isRotatingRectangles setting so that each screen saver instance will do the right thing.

Defaults

The NSUserDefaults system provides a very handy way of storing and retrieving user preferences in such a way that applications (and screen savers) don't have to care where the defaults are stored. Your code can just make the appropriate method invocations and the frameworks handle the rest. For screen savers, the ScreenSaverDefaults class makes things even easier. It provides a single method, defaults ForModuleWithName:, in addition to the standard methods provided by NSUserDefaults. Note that it is extremely important that your screen saver use the ScreenSaverDefaults mechanism rather than NSUserDefaults, which is keyed off the application that is reading and writing defaults. Since screen savers get loaded in by more than one application, you'll need to use the defaultsForModuleWithName: method of ScreenSaverDefaults to keep your preferences straight. As you might expect from the name, a screen saver uses defaultsForModuleWithName: to obtain a ScreenSaverDefaults reference that it can then use to load and store preferences. Let's see how that works in practice by adding code to handle our one preference value, isRotatingRectangles. First, we need to make sure that the defaults system knows what our global default for isRotatingRectangles should be (would that be a default default?) by registering a default dictionary.

1. Add the following define statements to projectNameView.h:

#define kDefaultsModuleName
                  @"projectName_Random_Rectangles"
   #define kDefaultsIsRotatingRectanglesKey
                  @"isRotatingRectanglesDefault"
   #define kDefaultsYesString            @"YES"

2. Declare a new helper method in projectNameView.h:

   - (ScreenSaverDefaults*) defaults;

3. Add the new helper method definition to projectNameView.m:

   - (ScreenSaverDefaults*) defaults {
      //  there's no need to cache this value so we'll make a handy accessor
      return [ScreenSaverDefaults defaultsForModuleWithName:
                  kDefaultsModuleName];
   }

4. Replace the assignment to isRotatingRectangles in initWithFrame:isPreview: with:

//  find the defaults we should use for this screen saver
   ScreenSaverDefaults* screenSaverDefaults =
                  [self defaults];
   //  create a dictionary to contain our global default values
   NSDictionary* defaultDict = [NSDictionary
                  dictionaryWithObject: kDefaultsYesString
                  forKey: kDefaultsIsRotatingRectanglesKey];
   //  register those global defaults
   [screenSaverDefaults registerDefaults: defaultDict];
   //  now we can read in the current default value knowing
   //  that we'll always get the user defaults or our global defaults
   //  if no user defaults have been set
   isRotatingRectangles = [screenSaverDefaults
                  boolForKey: kDefaultsIsRotatingRectanglesKey];

Before we move on, I should make a few comments about this code. Note that the defaultDictionary is created in an autoreleased state so we don't have to worry about cleaning it up to prevent leaks. As you'll see later, we also don't have to read the defaults back in right away since we'll be checking the default value of isRotatingRectangles before drawing each frame. So why is the boolForKey: call here? I included it for several reasons, not the least of which was reinforcement of the defaults idiom. It also makes sure that we've got the correct value of isRotatingRectangles from the very start in case we forget to check it later in the code. For example, the configuration sheet code sets the value of the checkbox based on the current value of isRotatingRectangles. If we forget to load the appropriate value before bringing up the sheet, the checkbox will be out of sync with the current default value and users will get confused. As a final comment on the initWithFrame:isPreview: code, note that we've now got two string key values: kDefaultsModuleName that represents the name of the module in the defaults system and kDefaultsIsRotatingRectanglesKey that we'll need to use whenever we want to access our default value. What else needs to change in order to correctly handle the default value? Well, as I mentioned above we'll be checking the default value in the drawRect: method so that we know whether or not to rotate the rectangles.

5. Add this code before if ( isRotatingRectangles ) in the drawRect: method of projectNameView.m:

isRotatingRectangles = [[self defaults]
                  boolForKey: kDefaultsIsRotatingRectanglesKey];

Checking here makes sure that if anybody changes the default value, even while we're running, we'll get the correct value and change our drawing style in mid-stream. One other important concept for user defaults that can be shared between different instances is that you need to update the defaults whenever the user changes a value. In our sample, the only place that the user gets to change anything is in the configuration sheet so we'll need to add a bit of code there.

6. Add the following code to the okSheetAction: method before we close the sheet in the projectNameView.m file:

   //  write out the current default so other instances of the saver pick up the change, too.
   [[self defaults] setBool: isRotatingRectangles
                  forKey: kDefaultsIsRotatingRectanglesKey];
   //  update the disk so that the screen saver engine will pick up the correct values
   [[self defaults] synchronize];

This code takes the latest version of the isRotatingRectangles variable and stores it in the screen saver's defaults. At the end there is a call to synchronize, but why? The synchronize call is there so that the true screen saver mode (invoked via the hot corner or system idle state) picks up the correct default value even if the System Preferences application is still running. This is technically just an implementation detail, but it turns out that while the Preview and Test modes share the in-memory defaults, due to the fact that they're both instantiated from the System Preferences process, there is a separate process that handles the full invocation of the screen saver module when your system has been idle for too long or you move the mouse into the Activate Screen Saver hot corner. The screen saver instance loaded by this ScreenSaverEngine application can only retrieve the latest defaults that have been written to disk and for screen saver modules that only seems to happen at two times: when the user quits the System Preferences application and when the screen saver explicitly calls synchronize.

For the purposes of this article, I've used a very generic scheme for the configuration sheet and its defaults. In this scheme the defaults are only updated and synchronized once the user is done changing all of the values. No changes are made to any defaults or screen saver state variables while the options sheet is open and the defaults only get updated once per invocation of the configuration sheet rather than on each control change. This style of configuration sheet also gives the user the option of canceling any changes they've made to the settings. The configuration sheet is one way to interact with and control a screen saver but screen savers can also react to a set of user input events much like any normal application. You can use these events to enable and disable effects, toggle status displays, and even turn your screen saver into a game! (Anybody remember Lunatic Fringe?) In the next section, we'll take a look at the methods you'll need to override to catch these events and handle them in your screen saver.

Handling Events

The view system in Cocoa provides a rich set of user input events that we can tap into while a screen saver is running. The implementation in the ScreenSaverView superclass uses most of the events as a signal to wake up the screen saver so the first thing we need to do is override that behavior in our subclass to prevent the saver from waking prematurely. Note: don't override all of the events or you won't be able to wake the screen saver at all!

1. Override the key handling code by adding the following implementations of methods inherited from the NSResponder class to projectView.m:

   - (void)keyDown:(NSEvent *)theEvent {
      //  handle any necessary keyDown events here and pass the rest on to the superclass
      [super keyDown: theEvent];
   }
   - (void)keyUp:(NSEvent *)theEvent {
      //  handle any necessary keyUp events here and pass the rest on to the superclass
      [super keyUp: theEvent];
   }

These methods simply pass all keyDown and keyUp events up to the superclass for it to handle. If, for example, we don't want keyDown events to wake the screen saver we can change the implementation of keyDown: by commenting out the call to super. However, we'll want to handle some keys ourselves and let the superclass handle others.

1. In that case, we can change the keyDown: code to look more like this:

//  handle any necessary keyDown events here and pass the rest on to the superclass
   if ( [[theEvent charactersIgnoringModifiers]
                  isEqualTo: @"g"] ) {
      //  the user pressed the "g" key so draw the next 50 rectangles in grayscale
      grayscaleRectanglesLeft += 50;
      //  note that the "g" key will no longer wake up the screen saver
   } else {
      [super keyDown: theEvent];
   }

We'll also need to add code to declare grayscaleRectanglesLeft and check for its value while drawing so make the following additional changes.

2. Add the declaration for grayscaleRectanglesLeft to projectNameView.h:

   int grayscaleRectanglesLeft;

3. Give grayscaleRectanglesLeft an initial value in initWithFrame:isPreview:

grayscaleRectanglesLeft = 0;

4. Change the color setup in drawRect: from this:

float red = SSRandomFloatBetween( 0.0, 1.0 );
      float green = SSRandomFloatBetween( 0.0, 1.0 );
      float blue = SSRandomFloatBetween( 0.0, 1.0 );
      float alpha = SSRandomFloatBetween( 0.0, 1.0 );
      [[NSColor colorWithDeviceRed: red
                  green: green blue: blue alpha: alpha] set];
   to this:

   if ( grayscaleRectanglesLeft ) {
         float white = SSRandomFloatBetween( 0.0, 1.0 );
         float alpha = SSRandomFloatBetween( 0.0, 1.0 );

         [[NSColor colorWithDeviceWhite: white
                  alpha: alpha] set];
         grayscaleRectanglesLeft--;
      } else {
         float red = SSRandomFloatBetween( 0.0, 1.0 );
         float green = SSRandomFloatBetween( 0.0, 1.0 );
         float blue = SSRandomFloatBetween( 0.0, 1.0 );
         float alpha = SSRandomFloatBetween( 0.0, 1.0 );
         [[NSColor colorWithDeviceRed: red
                  green: green blue: blue alpha: alpha] set];
      }

If you run the new version of the screen saver, you'll find that while all the other keys still wake up the saver, the "g" key causes the saver to draw a series of rectangles in shades of gray instead of the usual random colors. You can further modify keyDown: to intercept and handle other keys to do whatever you like but there are some useful keys, most notably the function and arrow keys, that don't have simple character equivalents. The trick is knowing how to interpret the result of charactersIgnoringModifiers for these keys. The short answer is, you don't. The longer answer is that you'll need to extract the unichar value of the character before comparing it to one of the constants like NSUpArrowFunctionKey. Change the implementation of keyDown: again to look like the following code to see how to handle arrow keys as well.

1. Change keyDown: to look like this:

   NSString* eventCharacters =
         [theEvent charactersIgnoringModifiers];
   unichar firstCharacter =
         [eventCharacters characterAtIndex: 0];
   //  handle any necessary keyDown events here and pass the rest on to the superclass
   if ( [eventCharacters isEqualTo: @"g"] ) {
      //  the user pressed the "g" key so draw the next 50 rectangles in grayscale
      grayscaleRectanglesLeft += 50;
   } else if ( firstCharacter == NSUpArrowFunctionKey ) {
      //  the user pressed the up arrow so make the rectangles taller
      rectangleHeightMultiplier *= 2;
   } else if ( firstCharacter == NSDownArrowFunctionKey ) {
      //  the user pressed the down arrow so make the rectangles shorter
      rectangleHeightMultiplier /= 2;
   } else if ( firstCharacter == NSRightArrowFunctionKey ) {
      //  the user pressed the right arrow so make the rectangles wider
      rectangleWidthMultiplier *= 2;
   } else if ( firstCharacter == NSLeftArrowFunctionKey ) {
      //  the user pressed the left arrow so make the rectangles narrower
      rectangleWidthMultiplier /= 2;
   } else {
      [super keyDown: theEvent];
   }

2. Add the declarations to projectNameView.h

   float rectangleHeightMultiplier;
   float rectangleWidthMultiplier;

3. Add some initial values to initWithFrame:isPreview: in projectNameView.m

//  set the starting multipliers to 1.0
   rectangleHeightMultiplier = 1.0;
   rectangleWidthMultiplier = 1.0;

4. Change the rectToFill line in drawRect: to this:

NSRect rectToFill =
         NSMakeRect( startingX, startingY,
               width * rectangleWidthMultiplier,
               height * rectangleHeightMultiplier );

Note that we're still handling "g" and passing other non-arrow events on to the superclass. With these changes, the arrow keys now control how wide and tall (or narrow and short) the random rectangles tend to be. Your screen saver might also need to handle the modifier key event which covers SHIFT, COMMAND, OPTION, and CONTROL. Unlike the other keys, the modifier keys don't send a keyDown: message. Instead, your screen saver needs to override the flagsChanged: method in your projectNameView.m to catch modifier key events.

1. Add the following method to projectNameView.m

   - (void)flagsChanged:(NSEvent *)theEvent {
      //  toggle the current sense of the isRotatingRectangles flag
      //  while the user is holding down the OPTION key
      if ( [theEvent modifierFlags] & NSAlternateKeyMask ) {
         reverseSenseOfIsRotatingRectangles = YES;
      } else {
         reverseSenseOfIsRotatingRectangles = NO;
      }
   }

2. Add the following declaration to the projectNameView.h file:

BOOL reverseSenseOfIsRotatingRectangles;

3. Set the initial value in initWithFrame:isPreview:

//  start out with isRotatingRectangles meaning what it says
   reverseSenseOfIsRotatingRectangles = NO;

4. Check the value in drawRect: by replacing the rotate code with:

BOOL rotateThisRectangle = isRotatingRectangles;
   if ( reverseSenseOfIsRotatingRectangles ) {
      rotateThisRectangle = !rotateThisRectangle;
   }
   if ( rotateThisRectangle ) {
      NSAffineTransform* rotation =
            [NSAffineTransform transform];
      float degrees = SSRandomFloatBetween( 0.0, 360.0 );
      [rotation rotateByDegrees: degrees];
      [rotation concat];
   }

With those small changes, your screen saver should now temporarily reverse the sense of the isRotatingRectangles flag as long as you hold down the OPTION key. The only other events that you're likely to want to capture are mouse events and they're just as easy. NSResponder provides a series of methods you can override for mouse movement, dragging, clicks, and even scroll wheel activity. Depending on your requirements, you might not need to trap and deal with every event right when it happens. If your screen saver merely adjusts its drawing based on the current mouse position, you may be able to simply query the system inside drawRect: using the NSEvent class method mouseLocation which returns the current mouse position in global coordinates.

Note: watch out for multiple monitors and Preview mode here. Don't assume that the mouse position will remain within the bounds of your view or even the main display. Users with multiple monitors will be disappointed if your screen saver fails or misbehaves just because they've plugged in another display.

Different Drawing APIs

Up until this point, we've been using the drawing functionality provided by Quartz 2D and built into Cocoa. While NSBezierPath does provide for easy, accessible drawing code, there are times when you need to do more that draw lines, rectangles, curves, etc. This is often the case if you already possess some drawing code that you're merely trying to wrap up in a screen saver. The first step beyond NSBezierPath is to use NSImage to load and draw images during drawRect:, perhaps to provide a backdrop or for use as sprites in your animation. NSImage is very simple to use and provides support for many common image types. In a typical screen saver, you'll store your images in the Resources folder within the screen saver bundle and load them in with code similar to the following:

   NSBundle* saverBundle =
            [NSBundle bundleForClass: [self class]];
   NSString* imagePath = [saverBundle
            pathForResource: @"test image" ofType: @"JPG"];
   NSImage* image =
         [[NSImage alloc] initWithContentsOfFile: imagePath];

Drawing the image such that it fills the entire view is simply a matter of calling the following NSImage method:

   NSSize imageSize = [image size];
   NSRect imageRect = NSMakeRect( 0, 0,
         imageSize.width, imageSize.height );
   [image drawInRect: viewBounds fromRect: imageRect
         operation: NSCompositeCopy fraction: 1.0];
   [image release];

In a real screen saver, you'd most likely want to load any images you need in startAnimation and keep them around until stopAnimation or even projectNameView's dealloc method since it is very inefficient to load the image in for every frame. You may even want to provide an accessor method like the following that handles loading an image the first time it is needed.

   - (NSImage*) backgroundImage {
      if ( backgroundImage == nil ) {
         NSBundle* saverBundle =
               [NSBundle bundleForClass: [self class]];
         NSString* imagePath = [saverBundle
               pathForResource: @"test image" ofType: @"JPG"];
         backgroundImage = [[NSImage alloc]
               initWithContentsOfFile: imagePath];
      }
      return backgroundImage;
   }

As you move beyond Cocoa, you may require some bit of functionality from Quartz 2D that Cocoa doesn't expose. Not to worry. Cocoa makes it easy to drop down and call Quartz 2D directly. When the system calls your screen saver's drawRect: method, the drawing environment is already set up for you. You can draw immediately with Cocoa as we've seen or you can ask Cocoa for the CGContextRef that you'll need to make Quartz 2D drawing calls. The code to retrieve the context looks like this:

   CGContextRef context =
         [[NSGraphicsContext currentContext] graphicsPort];

Add that line and the following code to the end of drawRect: to draw with Quartz 2D:

   CGContextSetRGBFillColor( context, 1.0, 0.0, 0.0, 1.0 );
   CGContextSetRGBStrokeColor(context, 0.0, 0.0, 1.0, 1.0 );
   CGContextBeginPath( context );
   CGContextAddArc( context, NSMidX( viewBounds ),
         NSMidY( viewBounds ), NSHeight( viewBounds ) / 4.0,
         0.0, 2 * 3.14159, 0 );
   CGContextClosePath( context );
   CGContextDrawPath( context, kCGPathFillStroke );
   CGContextFlush( context );

This code draws a large red circle with a blue outline in the middle of the screen as you can see from Figure 6. If you add this code after the rotating rectangle code from our basic screen saver and isRotatingRectangles is true, you'll notice that the circles don't draw in the middle of the screen any more. Why not, you ask? Because the Cocoa drawing APIs are layered on top of Quartz 2D, that means that they share the same drawing environment, including the underlying transformation matrix. When the Cocoa code uses NSAffineTransform to rotate the drawing of the rectangle, that rotation also applies to any subsequent Quartz 2D code. The moral of the story is to pay attention to any changes you make to the Cocoa or Quartz 2D drawing state since one affects the other.

Summary

Well, that brings us to the end of our series on screen savers. In this article we've added a configuration sheet to our screen saver, stored and reloaded the resulting default value, learned how to handle keyboard and mouse events, and investigated NSImage and Quartz 2D. Now you've got the information in hand to go out and write some really cool screen savers.

David Hill is a freelance writer living in College Station, Texas. In a former life, he worked in Apple's Developer Technical Support group helping developers print, draw, and write games. In his free time he dabbles in screen savers and other esoteric topics.