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.
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:
. This message is sent to the application’s service provider object.NSPortName
is the name of the port on 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. This property is ignored for Automator workflows being used as services.NSMenuItem
is a dictionary that specifies the text of the Services menu item. Only one entry should be in this dictionary, and its key should bedefault
. Its string value is used as the menu item’s text. There are no submenus in the Services menu, so the text preceding and including any slash present is discarded. (In OS X version 10.5 and earlier, you could 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.)Any services with identical names are disambiguated by adding the application name providing each service in parentheses after its name. (In OS X version 10.5 and earlier,
NSMenuItem
must be unique, as only one is used in the Services menu if there are duplicates.)To localize the string specified, create a
ServicesMenu.strings
file for each localization in your bundle with the abovedefault
menu item string as the lookup key. For example, create a.strings
file that hasSend Selection
as the key and the localized text as its value. (See Resource Programming Guide for details on localized strings files.) If a localized string is not found, thedefault
text is used.NSKeyEquivalent
is an optional dictionary that specifies the keyboard equivalent for invoking the menu command. LikeNSMenuItem
, the only entry in the dictionary should have the keydefault
with a string value that can be localized in theServicesMenu.strings
file. The string value must be a single character. The keyboard shortcut is this one character, with the Command key modifier. If the character is uppercase, the Shift modifier is also used.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.
NSRestricted
is an optional boolean that, when set toYES
, indicates the service does something that might enable an app that adopts App Sandbox to escape from its sandbox. If set toNO
, or left unspecified, the service is considered sandbox safe. For more information about App Sandbox, see the App Sandbox Design Guide.When a sandboxed app attempts to invoke a service marked as restricted, the system warns the user and asks for explicit permission to continue. This prevents a compromised app from invoking the service programmatically without the user’s consent. Services not marked as restricted do not trigger a user warning.
This property has no effect when the invoking app is not sandboxed.
NSSendTypes
is an optional array that contains data type names. Send types are the types sent from the application requesting a service. NSPasteboard Class Reference lists several common data types. Additionally, in OS X version 10.5 and later, Uniform Type Identifiers may be used. (See Uniform Type Identifiers Overview for more information on Uniform Type Identifiers.) This key is not required. (In OS X version 10.5 and earlier, an application that provides a service must specifyNSSendTypes
,NSReturnTypes
, or both.)NSReturnTypes
is an optional 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. Additionally, in OS X version 10.5 and later, Uniform Type Identifiers may be used. (See Uniform Type Identifiers Overview for more information on Uniform Type Identifiers.) This key is not required. (In OS X version 10.5 and earlier, an application that provides a service must specifyNSSendTypes
,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 sameNSMessage
value for all of them (each service invokes the same method) and use differentNSUserData
values to distinguish between them. This entry is also useful for applications that provide open-ended, or add-on, services. This property is ignored for Automator workflows being used as services.NSTimeout
is an optional numerical string that indicates the number of milliseconds that 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).Users may also press the Escape key or type Command-period to cancel.
NSSendFileTypes
is an array that contains file type names. Only Uniform Type Identifiers are allowed; pasteboard types are not permitted. (See Uniform Type Identifiers Overview for more information on Uniform Type Identifiers.) By assigning a value to this key, your service declares that it can operate on files whose type conforms to one or more of the given file types. Your service will receive a pasteboard from which you can read file URLs. You may specify values for bothNSSendTypes
andNSSendFileTypes
if your service can operate on both pasteboard data and files.NSServiceDescription
is a string that contains a description of your service that is suitable for presentation to users. It can be localized via theServicesMenu.strings
file.The description may be long. If your description is long, the value of
NSServiceDescription
should be a short token, such asSERVICE_DESCRIPTION
. The full text should be given in theServicesMenu.strings
file with that token as its key.NSRequiredContext
is a dictionary that can be used to limit when the service appears. Through judicious use ofNSRequiredContext
, you can ensure that your service appears only when it applies and does not clutter the Services menu when it is not applicable.NSRequiredContext
may be a dictionary that contains any of the following keys, all of which are optional. It may also be an array of such dictionaries, in which case the service is enabled if any of the given contexts is satisfied.NSApplicationIdentifier
NSTextScript
NSTextLanguage
NSWordLimit
NSTextContent
These keys have the following significance:
NSApplicationIdentifier
is a bundle ID as a string or an array of such IDs. Your service will appear only if the bundle ID of the current application matches one of the given bundle IDs. For example, you could use this to limit a service to appear only in Xcode or in the Finder.NSServiceCategory
is a UTI or category name as a string. If you provide a UTI, your service will appear in the category that corresponds to the provided UTI. For example, “public.text” will cause your service to appear in the Text category, while “public.source-code” will put it in the Development category. If you provide a literal category name, such as “Internet”, your service will appear there.You can not establish new categories with this key, but it does allow you to control which existing category a service appears in. Behavior for values that don’t match an existing category is undefined.
NSTextContent
is a string specifying a data type that the text must contain, or an array of such strings. The valid values are as follows:URL
Date
Address
Email
FilePath
The service is available only if the selected text contains one of the specified data types. All text selected is provided to the service-vending application, not just the parts found to contain the given data types.
NSTextLanguage
is a string containing the required overall language of the selected text as a BCP-47 tag. It may also be an array of such strings. The service appears only if the BCP-47 tag of the overall language of the selected text matches one of the given tags.The matching is performed via the default language range matching scheme, which is a prefix-matching scheme. For example, the
NSTextLanguage
string “zh” matches text whose language is “zh-Hant”. This key is relevant only for services that accept text.NSTextScript
is a string containing a standard four-letter script tag, such asLatn
orCyrl
. It may also be an array of such strings. The service will only appear if the dominant script of the selected text is text corresponding to one of the given script tags. This key is relevant only for services that accept text.NSWordLimit
is an integer representing the maximum number of selected words that the service operates on. For example, a service to look up a stock by ticker symbol might have anNSWordLimit
of 1 because ticker symbols cannot contain spaces. It may not be an array. This key is relevant only for services that accept text.
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’s NSServices
property. The property uses the application’s NSMessage
and NSPortName
values.
Sample Property List
The NSServices
property for Safari is shown in Figure 1 as it appears in the Property List Editor application.
The NSServices
property has one entry that represents the only service offered by Safari: “Search with Google.” Note that, for this entry, the port name is Safari. As mentioned, the port name is usually the application name.
The entry has one return type, NSStringPboardType
. An application can have more than one return type per entry, and the return types don’t necessarily need to be the same for each entry. Both Uniform Type Identifiers and pasteboard types are valid here. (For more information on Uniform Type Identifiers, see Uniform Type Identifiers Overview.)
The entry has a key equivalent of L, which means that Command-L can be used to invoke the service.
Copyright © 2003, 2016 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2016-09-13