To show how services work, we’re going to modify the GraphPaper application so that it is accessible through the Services menus of other applications. The graph service will take a formula selected by the user, graph it using the current graph parameters, and return the completed graph. To perform this operation, the method that implements the service will need to read a formula from the pasteboard, draw the graph, and then put the graph back on the pasteboard.

GraphPaper requires a few minor modifications and one significant one to work as a service. The minor modifications will take care of advertising the service, receiving the service message, making the graph, and returning the result. This is all fairly straightforward and will be based on the same pasteboard code that we have developed up to this point.

The significant modification will allow the service provided to initiate a graph and determine when the graph is completed. When GraphPaper is running as a service, it will not use the standard Cocoa event loop. Instead, it will run its own modal session.

A modal session is like the standard application event loop that we have used until now, except the application object ignores events from all windows other than the window designated in the runModalSession: message. This is how Cocoa implements Alert alerts.

The GraphView object will signal that the graph is finished by sending the stop: message to NSApp. This method is normally used to stop the main event loop. When you are running a modal session, it stops the modal session, which then returns control to the location where the modal session was started. In our example, it will return control to our Controller object and signal for the completed graph to be sent to the application that requested the service.

Don’t worry if this seems complicated — it will be quite simple to implement.

Services advertisements are stored in the Info.plist file that is one of the application resources. The Info.plist file is in XML format and should not be edited directly. Instead, you should use PB to edit it.

Unfortunately, with Mac OS X Version 10.1 it is necessary to (painstakingly) use PB’s “Expert” XML editing mode to manually create the XML structure necessary for the Services advertisement (PropertyListEditor is about the same hassle). It is possible that Apple will have added an easier-to-use mode for creating Services advertisements by the time you read this book — if so, you might want to experiment with it. Nevertheless, even if such a “Services wizard” is created, the following steps should still work.

Figure 20-4. New sibling renamed NSServices

Figure 20-5. The completed NSServices property list

This advertisement tells Mac OS X that your service should have a single menu item, Services → Graph Formula, which responds to the message graphFormula:userData:error:.

We have now completed the advertisement. However, the Services menu will not display the advertisement unless we place an application containing the advertisement in one of the directories that is monitored by the Services system.

As of Mac OS X Version 10.1, the Services system scans for advertisements for only those applications in the directories listed in Table 20-2. Our application is not currently in any of these locations, so its services will not appear in the Services menu!

Before we check to see if the new service works, we’ll verify that the Info.plist file in your newly built GraphPaper application contains the XML property list for your Services advertisement. The easiest way to do that is to use the PropertyListEditor application in the /Developer/Applications folder.

Figure 20-6. GraphPaper’s Info.plist file as viewed in PropertyListEditor

You can also view the Info.plist file’s contents in a Terminal shell window using the Unix cat command, as follows:

cat ~/GraphPaper/build/GraphPaper.app/Contents/Info.plist

but the output is less palatable.

Next, we’ll duplicate our application and put the copy in a directory that gets scanned for services.

When you log back into your computer, the Services system will begin scanning the monitored directories for any new applications. When the Services system finds GraphPaper alias, it will discover the Info.plist file and read the Services advertisement. (If this doesn’t work, try restarting and even shutting down your computer. If you’ve configured the Info.plist correctly, the service should show up eventually.)

In the following steps, we will modify the GraphView class so that it can be effectively commanded by the Controller class to run as a service.

We’ll use the runningAsService instance variable to tell GraphView that it should stop the modal loop when the graph is finished being drawn.

This addition causes the stop: message to be sent to GraphPaper’s Application object when the graph is stopped or finished.

That’s it for the changes to GraphView.

Finally, we need to modify the Controller class to register as a service so that it can receive the advertisement, and to actually handle the services request when that request arrives.

Services registration should be the last thing that your application does before it starts to accept events, because your application may receive a services request right after it registers. Thus, we cannot register for receiving services requests in an awakeFromNib or an initWithFrame: method (which may be followed by additional initializations). Instead, we will register our service in the application delegate method applicationDidFinishLaunching: .

This method sets the Controller object as the services provider. You must do this in order to receive services messages. The call to NSLog( ) is for our benefit — it tells us that the application has properly initialized. When you are running the application from within PB, you’ll see this notice in the PB window (Run pane). Otherwise, the notice will be visible within the Console application.

Although this graphFormula:userData:error: method may seem complex, it’s fairly self-explanatory. The method first sends the types message to the pasteboard, because if you don’t do that, you can’t read data from the object. Next it asks the pasteboard for its string data and puts this into the formula field, using the newly written setFormula: method. It then sends the graph: message to the GraphView object to start the graphing process.

Recall that the graph: message actually starts up the stuffer thread that sends (x,y) pairs to the Evaluator program. The results are read by the GraphView object because it has registered its gotData: method as an observer for the NSFileHandleReadCompletionNotification notification. All of this happens behind the scenes, as part of the application’s main event loop. When an application is being run as a service, however, you don’t want to be running the application’s main event loop, because you don’t want to be taking input from the user.

The way around this apparent conundrum is to create your own event loop, which Cocoa calls a modal session . This is what is done by the following command:

                  [NSApp runModalForWindow:[graphView window]];

This modal session runs until the GraphView object sends the stop: message to the NSApp object (which is done in the doStop: method).

So what’s with the call to NSEvent to create a periodic event? It turns out that when a modal session is created for a window, the NSApplication class will wake up only for events that are destined for that window and for timer events — not for events generated by a watched file handle. We use the NSEvent class to create a stream of periodic events. These periodic events cause the NSApplication class to wake up, at which point it checks the NSFileHandle object to see if there is any pending data. After the modal session, we need to terminate the stream of timed events — hence the bracketing of the runModalForWindow: message with the two messages to NSEvent:

                  [NSEvent startPeriodicEventsAfterDelay:0 withPeriod:0.1];
                  [NSApp runModalForWindow:[graphView window]];
                  [NSEvent stopPeriodicEvents];

By the way, you might try running this example with the two calls to NSEvent commented out, just to see how your application runs within a modal session. If you do this, you’ll see the graph appear whenever you generate an event in the GraphView window — for example, by clicking on the window or by choosing a menu.

When the modal session is finished, this method resets the runningAsService flag and copies the graph to the pasteboard that was provided by the Services manager. The copyToPasteboard: method puts the PDF representation of the graph on the pasteboard; if the requesting application wants the TIFF representation, this data will be provided through lazy evaluation. Finally, if the GraphPaper application was originally hidden, it hides itself again. This is good manners.

Well, it’s time to give everything a whirl.

Figure 20-7. Requesting the GraphPaper service from the TextEdit application

If GraphPaper is not already running, Mac OS X will start it up. GraphPaper will then generate the graph, and the graph will replace the selected formula in the word processor, as shown in Figure 20-8.

Figure 20-8. Result in TextEdit (top) after receiving GraphPaper-generated graph (bottom) via a Services menu request

If you get an “Error providing services Graph Formula” in PB’s Run pane, you probably made a spelling error in either the Info.plist file or the Controller.m file.