written by Brian Christensen

Writing a screen saver module is surprisingly simple using Mac OS X's screen saver framework. The ScreenSaverView class provides us with an interface for animating the screen saver, drawing the preview view in the System Preferences pane, and displaying a configuration sheet.

I originally wrote this article in 2001 when it was still necessary to jump through a few configuration hoops just to create a new screen saver project. An entire section was dedicated to "Preparing the Project." Thankfully, these steps are no longer required. Ever since the advent of Xcode Apple has included a default screen saver project template to make our lives significantly easier.

Having said that, this is not just a mere recycling of the old article. There is a considerable amount of fresh material which I hope will improve upon the original article.

Part 1: basics on set up, simple bezier path drawing, and user preferences using a configure sheet
Part 2: advanced topics such as setting up and using OpenGL for drawing

First, we'll need to create a new project. Launch Xcode and choose File > New Project. The window depicted below will appear:

From the list of choices you are presented with at this point select Screen Saver located under the Standard Apple Plug-ins category. Proceed to name the project MyScreenSaver (or any other name you prefer) and save it in your desired location. Once you have completed these steps, the project window will open.

Xcode automatically creates two files for us: MyScreenSaverView.h and MyScreenSaverView.m. Take a few minutes to poke around MyScreenSaverView.m and take note of the various methods that are provided for our use.

I have summarized some of these methods below:

We want to draw a bunch of shapes of random type, size, color, and location. This drawing magic must occur either in the drawRect: or animateOneFrame method. Since animateOneFrame is slightly easier to use and better suits our purpose, this is the method we will be using.

Open the "MyScreenSaverView.m" file to edit it. Scroll to the animateOneFrame method and add the following code:

First of all, we want to obtain the screen's boundaries for later use. To do this, we use the bounds method. This returns an NSRect from which we will obtain the size property.

Since we want our shapes to have random sizes, we can use the specially supplied SSRandomFloatBetween() function for this. For those who are wondering, it is automatically seeded by the screen saver framework, so there is no need to manually deal with that.

Now we want to calculate a random origin point for our shape. To do this, we use the handy SSRandomPointForSizeWithinRect() function, which will do all the work for us.

In simple terms, an NSBezierPath object lets you draw paths consisting of straight and curved line segments. When put together these can form shapes such as rectangles, ovals, arcs, and glyphs. We will be using the first three in our code.

We want to randomly decide whether to create our NSBezierPath object as a rectangle, oval, or arc. In order to provide for greater flexibibility should you choose to invent additional shape types at a later time, we will utilize a switch statement.

The arc case is a bit more complicated, so we will go through it step-by-step. An arc consists of a center, a radius, a starting angle, an ending angle, and a direction. First, we will select random starting and ending angles between 0 and 360 degrees. (Naturally, as you can see in the code below, it wouldn't make sense for the ending angle to start before the starting angle. Hence, it will not necessarily fall between 0 and 360 degrees. It is actually chosen to be somewhere between the starting angle value and the starting angle value plus 360.)

Similarly, we now choose a random radius. Since we already did a calculation earlier to determine a random rectangle size, we will simply use either the width or the height of that size, whichever is the smallest. In addition, we also calculate a center point using previously generated origin and size values.

Finally, we are ready to construct our path. Unlike the above rectangle and oval cases, here we must first create an empty bezier path and then append the arc path to it.

Naturally, we want to use random colors for our shapes, too. Take special note of the alpha parameter, which will create a nice transparency effect.

Last, but not least, use the set method to set the color used to draw our shape to the screen. In keeping with the tradition we have established so far, we will again randomly determine whether to draw a filled shape or an outlined shape (using either fill or stroke).

It's time to test the screen saver. Select Build > Build. When the process is finished, go to the Finder and open the build folder located inside of your MyScreenSaver project folder. You should see a MyScreeSaver.saver file in there.

To test your screen saver simply double-click the file. This will open System Preferences and present you with a dialog to allow you to automatically install the screen saver.

If you make changes in the code and rebuild your project later, the next time you double-click the file System Preferences will conveniently ask you if you want to replace the old version. (Please note that you may need to quit and relaunch System Preferences for it to reload your screen saver module.)

Although we could actually stop here since we now have a fully functioning screen saver, we, of course, will not. We want to make our screen saver even better by providing a few customization options through the use of a so-called "configure sheet." To save a bit of work, I have prepared the NIB file.

This NIB file has a bunch of outlets which we need to let our screen saver view know about. Edit MyScreenSaverView.h and add the following code:

To let the "Desktop & Screen Saver" system preference pane know that it should enable the "Options" button for our screen saver, we need to change our hasConfigureSheet method to return YES.

Furthermore, we need to load our NIB file and return a pointer to our sheet, which we do by implementing the following code in our configureSheet method.

Before we can do a quick sanity check test run, we need to add one more method.

To make sure that everything has gone smoothly so far, build the project and double-click the resulting MyScreenSaver.saver file to install it. Once System Preferences has opened, click the "Options" button for our screen saver and the configure sheet should appear.

Now that we have a working configure sheet, we'd like it to actually do something useful. Fortunately, implementing preferences in screen savers is not significantly different than in any other Cocoa application. We will use the ScreenSaverDefaults class, a subclass of NSUserDefaults. This is a convenient and simple way of dealing with user preferences.

The first step is to register our default values, the factory settings. First, add this constant somewhere towards the top of our ".m" file (directly under @implementation, for instance, would be fine):

(N.B.: Ideally, the com.yournamehere.MyScreenSaver string should match the corresponding string you are using in your project settings.)

Now, add the missing lines to the initWithFrame:isPreview: method so that it looks like this:

Trudging on, let's implement the okClick: method. This is the method that will be invoked when the user clicks "OK" in the configuration sheet, so what we need to do is simply update the defaults to reflect the settings selected in the sheet.

Lastly, we want the sheet to reflect the values in the preferences file when it is displayed. Navigate to the configureSheet method and update it as necessary to contain the following code:

Now that we have the defaults set up and ready to go, we want to actually utilize them during our animation drawing. As you will see, doing so is quite simple. Scroll to the animateOneFrame method and add the following line to the list of local method variables:

Continue scrolling down to the last section of code in the same method, which should be this:

Replace the above block with the following:

That's it. Hit build and take your new screen saver module for a test run.

Finished MyScreenSaver project for Xcode

You've written your first screen saver for Mac OS X. Certainly you must be hungry for more, so take a look at Write a Screen Saver: Part II, which covers more advanced topics including the use of OpenGL to do the drawing. It also explains important issues regarding symbol clashes and what conventions to use to prevent such problems (of which you should be aware before you release a screen saver into the wild).

As always, let us know what you think about the tutorial.

Further Reading

	Write a Screen Saver: Part II	advanced screen saver techniques
	ScreenSaverView Class Reference	Apple's reference documentation

author: Brian Christensen / © 2005 Brian Christensen, Cocoa Dev Central