---

Services Properties

Any application that has one or more services to provide must advertise the type of data its services can handle. Services are advertised through the NSServices property of the application’s information property list (Info.plist file).

Contents:

Property Definitions
Add-On Services
Sample Property List

Property Definitions

NSServices is a property whose value is an array of dictionaries that specifies the services provided by the application. Keys for each dictionary entry, are as follows:

• NSMessage indicates the instance method to invoke. Its value is used to construct an Objective-C method of the form messageName:userData:error: or a Java method of the form messageName(NSPasteBoard,String). This message is sent to the application’s service provider object.

• NSPortName is the name of the port to which the application should listen for service requests. Its value depends on how the service provider application is registered. In most cases, this is the application name.

• NSMenuItem is a dictionary that specifies the text of the Services menu item. The solitary entry has the key default. Its string value is the menu item text. You can use a slash to specify a submenu. For example, Mail/Send Selection appears in the Services menu as a submenu named Mail with an item named Send Selection. NSMenuItem must be unique, as only one is used in the Services menu if there are duplicates.

  To localize the string, create a ServicesMenu.strings file for each localization in your bundle with the above default menu item string as the lookup key. For example, create a .strings file that has Mail/Send Selection as the key and the localized text as its value. (See System Overview for details on localized strings files.) If a localized string is not found, the default text is used.

• NSKeyEquivalent is an optional dictionary that specifies the keyboard equivalent that invokes the menu command. Like NSMenuItem, the only entry in the dictionary should have the key default with a string value that can be localized in the ServicesMenu.strings file. The string value must be a single character. The keyboard shortcut is this one character with the Command and Shift key modifiers.

  Use key equivalents sparingly. Remember that your shortcuts are being added to the collection of shortcuts defined by each application as well as defined by the other services. When an application already has a shortcut with that key equivalent, the application’s shortcut wins. If multiple services define the same shortcut, which one gets invoked is undefined.

• NSSendTypes is an array that contains data type names. Send types are the types sent from the application requesting a service. The NSPasteboard class description lists several common data types. An application that provides a service must specify NSSendTypes, NSReturnTypes, or both.

• NSReturnTypes is an array that contains data type names. Return types are the data types returned to the application requesting a service. The NSPasteboard class description lists several common data types. An application that provides a service must specify NSSendTypes, NSReturnTypes, or both.

• NSUserData is an optional string that contains a value of your choice. You can use this string to customize the behavior of your service. For example, if your application provides several similar services, you can have the same NSMessage value for all of them (each service invokes the same method) and use different NSUserData values to distinguish between them. This entry is also useful for applications that provide open-ended, or add-on, services.

• NSTimeout is an optional numerical string that indicates the number of milliseconds Services should wait for a response from the application providing a service when a response is required. If the wait time exceeds the timeout value, the application aborts the service request and continues without interruption. If you don’t specify this entry, the timeout value is 30000 milliseconds (30 seconds).

Add-On Services

You typically define services when you create your application and advertise them in the Info.plist file of the application’s bundle. The services facility also allows you to advertise services outside of the application bundle, enabling you to create “add-on” services after the fact. This is where the NSUserData entry becomes truly useful: You can define a single message in your application that performs actions based on the user data provided, such as running the user data string as a UNIX command or treating it as a special argument in addition to the selected data that gets sent through the pasteboard. To define an add-on service, you create a bundle with a .service extension that contains an Info.plist file, which in turn contains the add-on service specification. The service specification uses the application’s NSMessage and NSPortName values.

Sample Property List

The NSServices property for the Grab application is shown in Figure 1 as it appears in the Property List Editor application.

The NSServices property has three entries, one for each service offered by Grab. The first entry is for the menu item Grab > Selection. The slash notation—Grab/Selection—specifies that Selection should be an item in the Grab submenu. (See Figure 4.)

Note that for each of the three entries, the port name is Grab. As mentioned, the port name is usually the application name.

Each entry has one return type, NSTIFFPboardType. An application could have more than one return type per entry, and the return types don’t necessarily need to be the same for each entry.

The entry for Grab/Timed Screen is the only entry that has a specified timeout value. This optional entry is needed in this case so that the Grab application can wait for the user to set up the screen before taking a screen shot.

---