NSWorkspace Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in OS X v10.0 and later. |
| Companion guide | |
| Declared in | NSRunningApplication.h NSWorkspace.h |
Overview
An NSWorkspace object responds to application requests to perform a variety of services:
Opening, manipulating, and obtaining information about files and devices
Tracking changes to the file system, devices, and the user database
Getting and setting Finder information for files.
Launching applications
There is one shared NSWorkspace object per application. You use the class method sharedWorkspace to access it. For example, the following statement uses an NSWorkspace object to request that a file be opened in the TextEdit application:
[[NSWorkspace sharedWorkspace] openFile:@"/Myfiles/README" |
withApplication:@"TextEdit"]; |
Tasks
Accessing the Shared NSWorkspace Instance
Accessing the NSWorkspace Notification Center
Opening Files
-
– openFile: -
– openFile:withApplication: -
– openFile:fromImage:at:inView: -
– openFile:withApplication:andDeactivate: -
– openURL: -
– openTempFile:Deprecated in OS X v10.6
Manipulating Applications
-
– launchApplication: -
– launchApplication:showIcon:autolaunch: -
– launchApplicationAtURL:options:configuration:error: -
– hideOtherApplications
Manipulating Files
-
– duplicateURLs:completionHandler: -
– recycleURLs:completionHandler: -
– performFileOperation:source:destination:files:tag: -
– activateFileViewerSelectingURLs: -
– selectFile:inFileViewerRootedAtPath:
Manipulating Uniform Type Identifier Information
-
– typeOfFile:error: -
– localizedDescriptionForType: -
– preferredFilenameExtensionForType: -
– filenameExtension:isValidForType: -
– type:conformsToType: -
– URLForApplicationWithBundleIdentifier:
Requesting Information
-
– iconForFile: -
– iconForFileType: -
– iconForFiles: -
– getInfoForFile:application:type: -
– URLForApplicationToOpenURL: -
– fullPathForApplication: -
– getFileSystemInfoForPath:isRemovable:isWritable:isUnmountable:description:type: -
– isFilePackageAtPath: -
– frontmostApplication -
– menuBarOwningApplication -
– activeApplicationDeprecated in OS X v10.7 -
– launchedApplicationsDeprecated in OS X v10.7
Image Animation
-
– slideImage:from:to:Deprecated in OS X v10.6
Requesting Additional Time Before Logout
Tracking Changes to the File System
-
– noteFileSystemChanged: -
– fileSystemChangedDeprecated in OS X v10.6 -
– noteFileSystemChangedDeprecated in OS X v10.6
Updating Registered Services and File Types
-
– findApplicationsDeprecated in OS X v10.6
Tracking Changes to the Defaults Database
-
– noteUserDefaultsChangedDeprecated in OS X v10.6 -
– userDefaultsChangedDeprecated in OS X v10.6
Tracking Status Changes for Applications and Devices
-
– runningApplications -
– checkForRemovableMediaDeprecated in OS X v10.6 -
– mountNewRemovableMediaDeprecated in OS X v10.6 -
– mountedLocalVolumePathsDeprecated in OS X v10.7 -
– mountedRemovableMediaDeprecated in OS X v10.7
Providing Custom Icons
Unmounting a Device
Working with Bundles
-
– absolutePathForAppBundleWithIdentifier: -
– launchAppWithBundleIdentifier:options:additionalEventParamDescriptor:launchIdentifier: -
– openURLs:withAppBundleIdentifier:options:additionalEventParamDescriptor:launchIdentifiers:
Managing the Desktop Image
-
– desktopImageURLForScreen: -
– setDesktopImageURL:forScreen:options:error: -
– desktopImageOptionsForScreen:
Performing Finder Spotlight Searches
Finder File Labels
Class Methods
sharedWorkspace
Returns the shared NSWorkspace instance.
Return Value
The NSWorkspace object associated with the process.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hInstance Methods
absolutePathForAppBundleWithIdentifier:
Returns the absolute file-system path of an application bundle.
Parameters
- bundleIdentifier
The bundle identifier string. This value corresponds to the value in the
CFBundleIdentifierkey of the application’sInfo.plistfile. For example, the bundle identifier of the TextEdit application iscom.apple.TextEdit.
Return Value
The file system path to the application bundle identified by bundleIdentifier, or nil if the bundle cannot be found.
Availability
- Available in OS X v10.3 and later.
Declared In
NSWorkspace.hactivateFileViewerSelectingURLs:
Activates the Finder, and opens one or more windows selecting the specified files.
Parameters
- fileURLs
The files to select and display in the Finder.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hdesktopImageOptionsForScreen:
Returns the desktop image options for the given screen.
Parameters
- screen
The screen for which to get the desktop image options.
Return Value
A dictionary containing key-value pairs specified in “Desktop Image Dictionary Keys.”
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hdesktopImageURLForScreen:
Returns the URL for the desktop image for the given screen.
Parameters
- screen
The screen for which to get the desktop image.
Return Value
The desktop image.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hduplicateURLs:completionHandler:
Duplicates the specified URLS asynchronously in the same manner as the Finder..
Parameters
- URLs
The array of URLs to duplicate.
- handler
The completion handler block object. If completionHandler is not
nil, it will be called when the operation is complete, on the same dispatch queue that was used for theduplicateURLs:completionHandler:call. The completionHandler may be nil if you are not interested in the results.The block takes two arguments:
- newURLs
A dictionary parameter that maps the given URLs to their new URLs locations. Files that could not be duplicated will not be present in the dictionary.
- error
If the operation succeeded for every file, the error parameter will be nil. If it failed for one or more files, the error parameter will describe the overall result of the operation in a manner suitable for presentation to the user.
Discussion
This methods may show a progress indicator, or other user interface elements, at AppKit's discretion.
In OS X v10.6, this method require that the main run loop be run in a common mode.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSWorkspace.hextendPowerOffBy:
Requests the system wait for the specified amount of time before turning off the power or logging out the user.
Parameters
- requested
The number of milliseconds to wait before turning off the power or logging off the user.
Return Value
The number of milliseconds granted by the system.
Discussion
Currently unimplemented.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hfileLabelColors
Returns the corresponding array of file label colors for the file labels.
Return Value
An array of NSColor objects.
Discussion
This array has the same number of elements as fileLabels, and the color at a given index corresponds to the label at the same index.
You can listen for notifications named NSWorkspaceDidChangeFileLabelsNotification to be notified when file labels change which may result in changes to the order of the fileLabelColors.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSWorkspace.hfileLabels
Returns the array of file labels as strings.
Return Value
An array of strings.
Discussion
You can listen for notifications named NSWorkspaceDidChangeFileLabelsNotification to be notified when file labels change.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSWorkspace.hfilenameExtension:isValidForType:
Returns whether the specified filename extension is appropriate for the Uniform Type Identifier.
Parameters
- filenameExtension
A string containing the filename extension.
- typeName
A string containing the Uniform Type Identifier.
Return Value
YES if fileNameExtension is a valid extension for typeName, NO otherwise
Availability
- Available in OS X v10.5 and later.
Declared In
NSWorkspace.hfrontmostApplication
Returns the frontmost application, which is the application that receives key events.
Return Value
The running application instance for the application that receives key events..
Discussion
This value is key-value observing compliant.
Availability
- Available in OS X v10.7 and later.
Declared In
NSWorkspace.hfullPathForApplication:
Returns the full path for the specified application.
Parameters
- appName
The name of the application.
Return Value
The full path for the application, or nil if the specified application was not found.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hgetFileSystemInfoForPath:isRemovable:isWritable:isUnmountable:description:type:
Describes the file system at fullPath.
Parameters
- fullPath
The path to the file-system mount point.
- removableFlag
On input, a boolean variable; on return, this variable contains
YESif the file system is on removable media.- writableFlag
On input, a boolean variable; on return, this variable contains
YESif the file system writable.- unmountableFlag
On input, a boolean variable; on return, this variable contains
YESif the file system is unmountable.- description
On input, a pointer to a string object variable; on return, if the method was successful, this variable contains a string object that describes the file system. You should not rely on this description for program logic but can use it in message strings. Values can include “hard,” “nfs,” and “foreign."
- fileSystemType
On input, a pointer to a string object variable; on return, if the method was successful, this variable contains the file-system type. Values can include “HFS,” “UFS,” or other values.
Return Value
YES if the information was successfully returned, otherwise NO.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hgetInfoForFile:application:type:
Retrieves information about the specified file.
Parameters
- fullPath
The full path to the desired file.
- appName
The application the system would use to open the file.
- type
On input, a pointer to a string object variable; on return, if the method is successful, this variable contains a string object with the filename extension or encoded HFS file type of the file.
Return Value
YES if the information was retrieved successfully; otherwise, NO if the file could not be found or the application was not associated with the file.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSWorkspace.hhideOtherApplications
Hides all applications other than the sender.
Discussion
The user can hide all applications except the current one by Command-Option-clicking on an application’s Dock icon.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hiconForFile:
Returns an image containing the icon for the specified file.
Parameters
- fullPath
The full path to the file.
Return Value
The icon associated with the file.
Discussion
The returned image has an initial size of 32 pixels by 32 pixels.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hiconForFiles:
Returns an image containing the icon for the specified files.
Parameters
- fullPaths
An array of
NSStringobjects, each of which contains the full path to a file.
Return Value
The icon associated with the group of files.
Discussion
If fullPaths specifies one file, that file's icon is returned. If fullPaths specifies more than one file, an icon representing the multiple selection is returned.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSWorkspace.hiconForFileType:
Returns an image containing the icon for files of the specified type.
Parameters
- fileType
The file type, which may be either a filename extension or an encoded HFS file type.
Return Value
The icon associated with files of the given type.
Discussion
The returned image has an initial size of 32 pixels by 32 pixels.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSWorkspace.hisFilePackageAtPath:
Determines whether the specified path is a file package.
Parameters
- fullPath
The full path to examine.
Return Value
YES if the path identifies a file package; otherwise, NO if the path does not exist, is not a directory, or is not a file package.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hlaunchApplication:
Launches the specified application.
Parameters
- appName
The name of the application to open.
Return Value
YES if the application was successfully launched or was already running; otherwise, NO.
Discussion
The appName parameter need not be specified with a full path and, in the case of an application wrapper, may be specified with or without the .app extension, as described in “Use of .app Extension”.
Before this method begins, it posts an NSWorkspaceWillLaunchApplicationNotification to the NSWorkspace object’s notification center. When the operation is complete, it posts an NSWorkspaceDidLaunchApplicationNotification.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hlaunchApplication:showIcon:autolaunch:
Launches the specified application using additional options.
Parameters
- appName
The name of the application to open.
- showIcon
If
NO, the application's icon is not placed on the screen. (The icon still exists, though.)- autolaunch
If
YES, the autolaunch default is set as though the specified application were autolaunched at startup.
Return Value
YES if the application was successfully launched or was already running; otherwise, NO.
Discussion
This method is provided to enable daemon-like applications that lack a normal user interface. Its use is not generally encouraged.
Returns YES if the application is successfully launched or already running, and NO if it can’t be launched.
Before this method begins, it posts an NSWorkspaceWillLaunchApplicationNotification to the NSWorkspace object’s notification center. When the operation is complete, it posts an NSWorkspaceDidLaunchApplicationNotification.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSWorkspace.hlaunchApplicationAtURL:options:configuration:error:
Launches the app at the specified URL.
Parameters
- url
The application URL.
- options
Options to use when launching the application. See “NSWorkspaceLaunchOptions” for possible values.
- configuration
A dictionary containing the configuration options. Possible key-value pairs are described in “Workspace Launch Configuration Options”
- error
Returns ,by-reference, the error if the application was unable to be launched.
Return Value
If the app is already running, and NSWorkspaceLaunchNewInstance is not specified in the options dictionary, then a reference to the existing app is returned; otherwise a new application reference is returned. The the application could not be launched nil is returned, and the error is specified in error.
Discussion
The configuration dictionary can be used to pass additional options to the app. If the dictionary is nil, in which case default behavior applies.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hlaunchAppWithBundleIdentifier:options:additionalEventParamDescriptor:launchIdentifier:
Launches the application corresponding to the specified bundleIdentifier.
Parameters
- bundleIdentifier
A bundle identifier string. This value corresponds to the value in the
CFBundleIdentifierkey of the application’sInfo.plistfile. For example, the bundle identifier of the TextEdit application iscom.apple.TextEdit.- options
Options to use when launching the application. Values for this parameter are described in “NSWorkspaceLaunchOptions.”
- descriptor
Additional options specified in an AppleEvent-style descriptor. For example, you could use this parameter to specify additional documents to open when the application is launched.
- identifier
The launchIdentifiers are currently unused, and you should pass
NULL.
Return Value
YES if the application was found and launched; otherwise, NO.
Availability
- Available in OS X v10.3 and later.
See Also
Declared In
NSWorkspace.hlocalizedDescriptionForType:
Returns the localized description for the specified Uniform Type Identifier
Parameters
- typeName
A string containing the Uniform Type Identifier.
Return Value
An NSString containing the localized description of typeName.
Discussion
The localized description is suitable for displaying to the user.
Availability
- Available in OS X v10.5 and later.
Declared In
NSWorkspace.hmenuBarOwningApplication
Returns the application that owns the currently displayed menu bar.
Return Value
The running application instance for the application that owns the displayed menu bar.
Discussion
This value is key-value observing compliant.
Availability
- Available in OS X v10.7 and later.
Declared In
NSWorkspace.hnoteFileSystemChanged:
Informs the NSWorkspace object that the file system changed at the specified path.
Parameters
- path
The full path that changed.
Discussion
The NSWorkspace object then gets the status of all the files and directories it is interested in and updates itself appropriately. This method is used by many objects that write or delete files.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSWorkspace.hnotificationCenter
Returns the notification center for workspace notifications.
Return Value
The notification center object.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hopenFile:
Opens the specified file specified using the default application associated with its type.
Parameters
- fullPath
The full path to the file.
Return Value
YES if the file was successfully opened; otherwise, NO.
Discussion
The sending application is deactivated before the request is sent.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSWorkspace.hopenFile:fromImage:at:inView:
Opens a file using the default application for its type and animates the action using a custom icon.
Parameters
- fullPath
The full path to the file.
- anImage
The icon for the file.
- point
The point in
aViewat which to display the icon.- aView
The view in which to display the icon.
Return Value
YES if the file was successfully opened; otherwise, NO.
Discussion
The Finder provides an animation before opening the file to give the user feedback that the file is to be opened. To provide this animation, anImage should contain an icon for the file, and its image should be displayed at point, specified in the coordinates of aView. Currently provides the same functionality as openFile:.
The sending application is deactivated before the request is sent.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSWorkspace.hopenFile:withApplication:
Opens a file using the specified application.
Parameters
- fullPath
The full path to the file.
- appName
The name of the application to use when opening the file.
Return Value
YES if the file was successfully opened; otherwise, NO.
Discussion
The appName parameter need not be specified with a full path and, in the case of an application wrapper, may be specified with or without the .app extension, as described in “Use of .app Extension”. The sending application is deactivated before the request is sent.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hopenFile:withApplication:andDeactivate:
Opens the specified file and optionally deactivates the sending application.
Parameters
- fullPath
The full path to the file.
- appName
The name of the application to use when opening the file.
- flag
If YES, the sending application is deactivated before the request is sent, allowing the opening application to become the active application.
Return Value
YES if the file was successfully opened; otherwise, NO.
Discussion
The appName parameter need not be specified with a full path and, in the case of an application wrapper, may be specified with or without the .app extension, as described in “Use of .app Extension”. If appName is nil, the default application for the file’s type is used.
Availability
- Available in OS X v10.0 and later.
See Also
-
– openFile: -
– openFile:withApplication: -
application:openFile:(NSApplicationDelegate)
Declared In
NSWorkspace.hopenURL:
Opens the location at the specified URL.
Parameters
- url
A URL specifying the location to open.
Return Value
YES if the location was successfully opened; otherwise, NO.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hopenURLs:withAppBundleIdentifier:options:additionalEventParamDescriptor:launchIdentifiers:
Opens one or more files from an array of URLs.
Parameters
- urls
An array of
NSURLobjects, each one identifying a URL for the application to open.- bundleIdentifier
A bundle identifier string or
nilto use the default system bindings. This value corresponds to the value in theCFBundleIdentifierkey of the application’sInfo.plistfile. For example, the bundle identifier of the TextEdit application iscom.apple.TextEdit.- options
Options to use when launching the application. Values for this parameter are described in “NSWorkspaceLaunchOptions.”
- descriptor
Additional options specified in an AppleEvent-style descriptor. For example, you could use this parameter to specify additional documents to open when the application is launched.
- identifiers
The launchIdentifiers are currently unused, and you should pass
NULL.
Return Value
YES if the application was found and launched; otherwise, NO.
Availability
- Available in OS X v10.3 and later.
Declared In
NSWorkspace.hperformFileOperation:source:destination:files:tag:
Performs a file operation on a set of files in a particular directory.
Parameters
- operation
The file operation to perform. The possible values for this parameter are described in “File Operations.”
- source
The full path to the directory containing the files on which to operate.
- destination
The full path to the destination directory of the operation.
- files
An array of
NSStringobjects specifying the names of the files and directories to be manipulated. Each string must not contain any path information other than the name of the file or directory. In other words, all of the files and directories must be located in the source directory and not in one if its subdirectories.- tag
On input, a integer variable; on return, this variable contains a negative integer if the operation fails, 0 if the operation was performed synchronously and succeeded, or a positive integer if the operation was performed asynchronously. If the value is a positive integer, the value is a tag that identifies the requested file operation.
Return Value
YES if the operation succeeded; otherwise, NO.
Discussion
Some operations—such as moving, copying, and linking files—require a destination directory to be specified. If not, destination should be the empty string (@""). Before this method returns, it posts an NSWorkspaceDidPerformFileOperationNotification to the NSWorkspace object's notification center.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hpreferredFilenameExtensionForType:
Returns the preferred filename extension for the specified Uniform Type Identifier.
Parameters
- typeName
A string containing the Uniform Type Identifier.
Return Value
The appropriate filename extension for typeName, or nil if no extension could be determined.
Availability
- Available in OS X v10.5 and later.
Declared In
NSWorkspace.hrecycleURLs:completionHandler:
Moves the specified URLs to the trash in the same manner as the Finder.
Parameters
- URLs
The array of URLs to move to the trash.
- handler
The completion handler block object. If completionHandler is not
nil, it will be called when the operation is complete, on the same dispatch queue that was used for therecycleURLs:completionHandler:call. The completionHandler may be nil if you are not interested in the results.The block takes two arguments:
- newURLs
A dictionary parameter that maps the given URLs to their new URLs locations in the trash. Files that could not be moved to the trash will not be present in the dictionary.
- error
If the operation succeeded for every file, the error parameter will be nil. If it failed for one or more files, the error parameter will describe the overall result of the operation in a manner suitable for presentation to the user.
Discussion
This methods may show a progress indicator, or other user interface elements, at AppKit's discretion.
In OS X v10.6, this method require that the main run loop be run in a common mode.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSWorkspace.hrunningApplications
Returns an array of NSRunningApplication representing the running applications.
Return Value
An array of NSRunningApplication instances.
Discussion
The order of the array is unspecified, but it is stable, meaning that the relative order of particular applications will not change across multiple calls to runningApplications. See NSRunningApplication Class Reference for more information on NSRunningApplication.
Similar to the NSRunningApplication class’s properties, this property will only change when the main run loop is run in a common mode. Instead of polling, use key-value observing to be notified of changes to this array property.
This property is thread safe, in that it may be called from background threads and the result is returned atomically.
This property is observable using key-value observing.
Availability
- Available in OS X v10.6 and later.
Declared In
NSRunningApplication.hselectFile:inFileViewerRootedAtPath:
Selects the file specified by fullPath.
Parameters
- fullPath
The full path of the file to select.
- rootFullPath
If a path is specified, a new file viewer is opened. If you specify an empty string (
@"") for this parameter, the file is selected in the main viewer.
Return Value
YES if the file was successfully selected; otherwise, NO.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hsetDesktopImageURL:forScreen:options:error:
Sets the desktop image for the given screen to the image at the specified URL.
Parameters
- url
A file URL to the image. The URL must not be nil.
- screen
The screen to set the desktop image on.
- options
The options dictionary may contain any of the “Desktop Image Dictionary Keys” keys, which control how the image is scaled on the screen.
- error
A error that is returned by-reference if setting the image fails.
Return Value
YES if the image was set as the desktop, otherwise NO. If NO is returned, the error parameter provides additional information.
Discussion
You should not present a user interface for picking the options. Instead, choose appropriate defaults and allow the user to adjust them in the System Preference Pane.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hsetIcon:forFile:options:
Sets the icon for the file or directory at the specified path.
Parameters
- image
The image to use as the icon for the file or directory.
- fullPath
The full path of the file or directory.
- options
The icon representations to generate from the image. You specify this value by combining the appropriate “Workspace icon creation options” constants, using the C bitwise
ORoperator. Specify0if you want to generate icons in all available icon representation formats.
Return Value
YES if the icon was set; otherwise, NO.
Discussion
The image can be an arbitrary image, with or without transparency. This image is automatically scaled (as needed) to generate the icon representations. The file or folder must exist and be writable by the user.
It is recommended that applications include the NSExclude10_4ElementsIconCreationOption option for compatibility with pre-OS X v10.3 Finder. Icons that include the high resolution elements prevent custom icons from being displayed on earlier systems.
Availability
- Available in OS X v10.4 and later.
Declared In
NSWorkspace.hshowSearchResultsForQueryString:
Displays a Spotlight search results window in Finder for the specified query string.
Parameters
- queryString
The string to search for.
Return Value
YES if the communication with Finder was successful, otherwise NO.
Discussion
Finder becomes the active application, if possible. The user can further refine the search via the Finder user interface.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.htype:conformsToType:
Returns a Boolean indicating that the first Uniform Type Identifier conforms to the second Uniform Type Identifier.
Parameters
- firstTypeName
A string containing the Uniform Type Identifier that should conform to secondTypeName.
- secondTypeName
A string containing a Uniform Type Identifier.
Return Value
YES if firstTypeName conforms to the uniform type identifier hierarchy of secondTypeName, NO otherwise.
Discussion
Use this method instead of comparing Uniform Identifier Types for equality. See Uniform Type Identifiers Overview for information about Uniform Type Identifier conformance.
This method will always return YES if the two strings are equal. It is appropriate to use this method with other type names, including those declared in CFBundleTypeName Info.plist entries.
Availability
- Available in OS X v10.5 and later.
Declared In
NSWorkspace.htypeOfFile:error:
Returns the uniform type identifier of the specified file, if it can be determined..
Parameters
- absoluteFilePath
The absolute path of the file.
- outError
If the Uniform Type Identifier of the file at absolutePath can’t be determined, outError contains an NSError object that describes why.
Return Value
An NSString containing the uniform type identifier of the file at absoluteFilePath. If no UTI can be determined the return value is nil.
Discussion
If the file at the specified path is a symbolic link, the type of the symbolic link is returned.
Availability
- Available in OS X v10.5 and later.
Declared In
NSWorkspace.hunmountAndEjectDeviceAtPath:
Unmounts and ejects the device at the specified path.
Parameters
- path
The path to the device.
Return Value
YES if the device was unmounted; otherwise, NO.
Discussion
When this method begins, it posts an NSWorkspaceWillUnmountNotification to the NSWorkspace object’s notification center. When it is finished, it posts an NSWorkspaceDidUnmountNotification.
The unmountAndEjectDeviceAtURL:error: is preferable as it will provide more detailed error information.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSWorkspace.hunmountAndEjectDeviceAtURL:error:
Attempts to eject the volume mounted at the given path.
Parameters
- url
The URL of the volume to eject.
- error
If the operation fails, this error contains more information about the failure.
Return Value
YES if the volume was unmounted and ejected successfully, otherwise NO, for example, if the volume is not ejectable.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSWorkspace.hURLForApplicationToOpenURL:
Returns the URL to the default application that would be used to open the given URL.
Parameters
- url
The URL of the file to open.
Return Value
The URL of the default application that would open the specified url. Returns nil if no application is able to open the url, or if the file url does not exist.
Discussion
This is the programmatic equivalent of double clicking a document in the Finder.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hURLForApplicationWithBundleIdentifier:
Returns the URL for the application with the specified identifier.
Parameters
- bundleIdentifier
A bundle identifier specifying an application.
Return Value
The URL of the application, or nil if no application has the bundle identifier.
Discussion
This uses various (currently unspecified) heuristics in case multiple apps have the same bundle ID.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hConstants
The following table describes keys for an NSDictionary object containing information about an application. This dictionary is returned by activeApplication and launchedApplications, and is also provided in the userInfo of NSWorkspace notifications for application launch and termination.
Note that these constants are considered legacy.
Key |
Value |
|---|---|
|
The full path to the application, as a |
|
The application's name, as an |
|
The application’s bundle identifier, as an |
|
The application's process id, as an |
|
The high long of the process serial number (PSN), as an |
|
The low long of the process serial number (PSN), as an |
File Types
These constants specify different types of files returned by the getInfoForFile:application:type: method.
NSString *NSPlainFileType; NSString *NSDirectoryFileType; NSString *NSApplicationFileType; NSString *NSFilesystemFileType; NSString *NSShellCommandFileType;
Constants
NSPlainFileTypePlain (untyped) file
Available in OS X v10.0 and later.
Deprecated in OS X v10.6.
Declared in
NSWorkspace.h.NSDirectoryFileTypeDirectory
Available in OS X v10.0 and later.
Deprecated in OS X v10.6.
Declared in
NSWorkspace.h.NSApplicationFileTypeCocoa application
Available in OS X v10.0 and later.
Deprecated in OS X v10.6.
Declared in
NSWorkspace.h.NSFilesystemFileTypeFile-system mount point
Available in OS X v10.0 and later.
Deprecated in OS X v10.6.
Declared in
NSWorkspace.h.NSShellCommandFileTypeExecutable shell command
Available in OS X v10.0 and later.
Deprecated in OS X v10.6.
Declared in
NSWorkspace.h.
Declared In
NSWorkspace.hWorkspace Launch Configuration Options
The following keys can be used in the configuration dictionary of the launchApplicationAtURL:options:configuration:error: method. Each key is optional, and if omitted, default behavior is applied.
NSString * const NSWorkspaceLaunchConfigurationAppleEvent; NSString * const NSWorkspaceLaunchConfigurationArguments; NSString * const NSWorkspaceLaunchConfigurationEnvironment; NSString * const NSWorkspaceLaunchConfigurationArchitecture;
Constants
NSWorkspaceLaunchConfigurationAppleEventThe value is the first
NSAppleEventDescriptorto send to the new application. If an instance of the application is already running, this is sent to that application.Available in OS X v10.6 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchConfigurationArgumentsThe value is an
NSArrayofNSStrings, passed to the new application in theargvparameter. Ignored if a new instance of the application is not launched.Available in OS X v10.6 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchConfigurationEnvironmentThe value is an
NSDictionary, mappingNSStringstoNSStrings, containing environment variables to set for the new app. Ignored if a new instance of the application is not launched.Available in OS X v10.6 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchConfigurationArchitectureThe value is an NSNumber containing an
Mach-O Architectureconstant. Ignored if a new instance of the application is not launched.Available in OS X v10.6 and later.
Declared in
NSWorkspace.h.
File Operations
These constants specify different types of file operations used by performFileOperation:source:destination:files:tag:.
NSString *NSWorkspaceMoveOperation; NSString *NSWorkspaceCopyOperation; NSString *NSWorkspaceLinkOperation; NSString *NSWorkspaceCompressOperation; NSString *NSWorkspaceDecompressOperation; NSString *NSWorkspaceEncryptOperation; NSString *NSWorkspaceDecryptOperation; NSString *NSWorkspaceDestroyOperation; NSString *NSWorkspaceRecycleOperation; NSString *NSWorkspaceDuplicateOperation;
Constants
NSWorkspaceMoveOperationMove file to destination. Behaves the same as
movePath:toPath:handler:.Available in OS X v10.0 and later.
Declared in
NSWorkspace.h.NSWorkspaceCopyOperationCopy file to destination. Behaves the same as
copyPath:toPath:handler:.Available in OS X v10.0 and later.
Declared in
NSWorkspace.h.NSWorkspaceLinkOperationCreate hard link to file in destination. Behaves the same as
linkPath:toPath:handler:.Available in OS X v10.0 and later.
Declared in
NSWorkspace.h.NSWorkspaceCompressOperationCompress file. This operation always returns an error.
Available in OS X v10.0 and later.
Declared in
NSWorkspace.h.NSWorkspaceDecompressOperationDecompress file. This operation always returns an error.
Available in OS X v10.0 and later.
Declared in
NSWorkspace.h.NSWorkspaceEncryptOperationEncrypt file. This operation always returns an error.
Available in OS X v10.0 and later.
Declared in
NSWorkspace.h.NSWorkspaceDecryptOperationDecrypt file. This operation always returns an error.
Available in OS X v10.0 and later.
Declared in
NSWorkspace.h.NSWorkspaceDestroyOperationDestroy file. Behaves the same as
removeFileAtPath:handler:.Available in OS X v10.0 and later.
Declared in
NSWorkspace.h.NSWorkspaceRecycleOperationMove file to trash. The file is moved to the trash folder on the volume containing the file using the same semantics as
NSWorkspaceMoveOperation. If a file with the same name currently exists in the trash folder, the new file is renamed. If no trash folder exists on the volume containing the file, the operation fails.Available in OS X v10.0 and later.
Declared in
NSWorkspace.h.NSWorkspaceDuplicateOperationDuplicate file in source directory.
Available in OS X v10.0 and later.
Declared in
NSWorkspace.h.
Declared In
NSWorkspace.hDesktop Image Dictionary Keys
The following keys may be specified or returned in the options dictionary for setDesktopImageURL:forScreen:options:error:.
NSString * const NSWorkspaceDesktopImageScalingKey; NSString * const NSWorkspaceDesktopImageAllowClippingKey; NSString * const NSWorkspaceDesktopImageFillColorKey;
Constants
NSWorkspaceDesktopImageScalingKeyThe value is an
NSNumbercontaining anNSImageScalingconstant as declared inNSCell. If this is not specified,NSImageScaleProportionallyUpOrDownis used.NSImageScaleProportionallyDownis not currently supported.Available in OS X v10.6 and later.
Declared in
NSWorkspace.h.NSWorkspaceDesktopImageAllowClippingKeyThe value is an
NSNumbercontaining aBOOL, which affects the interpretation of Proportional scaling types. ANOvalue will make the image fully visible, but there may be empty space on the sides or top and bottom. AYESvalue will cause the image to fill the entire screen, but the image may be clipped. If this is not specified,NOis assumed. Non-proportional scaling types ignore this value.Available in OS X v10.6 and later.
Declared in
NSWorkspace.h.NSWorkspaceDesktopImageFillColorKeyThe value is an
NSColor, which is used to fill any empty space around the image. If not specified, a default value is used. Currently, only colors that use or can be converted to useNSCalibratedRGBColorSpaceare supported, and any alpha value is ignored.Available in OS X v10.6 and later.
Declared in
NSWorkspace.h.
NSWorkspaceLaunchOptions
These constants define launch options you can pass to launchAppWithBundleIdentifier:options:additionalEventParamDescriptor:launchIdentifier: and openURLs:withAppBundleIdentifier:options:additionalEventParamDescriptor:launchIdentifiers:.
enum {
NSWorkspaceLaunchAndPrint = 0x00000002,
NSWorkspaceLaunchInhibitingBackgroundOnly = 0x00000080,
NSWorkspaceLaunchWithoutAddingToRecents = 0x00000100,
NSWorkspaceLaunchWithoutActivation = 0x00000200,
NSWorkspaceLaunchAsync = 0x00010000,
NSWorkspaceLaunchAllowingClassicStartup = 0x00020000,
NSWorkspaceLaunchPreferringClassic = 0x00040000,
NSWorkspaceLaunchNewInstance = 0x00080000,
NSWorkspaceLaunchAndHide = 0x00100000,
NSWorkspaceLaunchAndHideOthers = 0x00200000,
NSWorkspaceLaunchDefault = NSWorkspaceLaunchAsync | NSWorkspaceLaunchAllowingClassicStartup
};
typedef NSUInteger NSWorkspaceLaunchOptions;
Constants
NSWorkspaceLaunchAndPrintPrint items instead of opening them.
Available in OS X v10.3 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchInhibitingBackgroundOnlyCauses launch to fail if the target is background-only.
Available in OS X v10.3 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchWithoutAddingToRecentsDo not add the application or documents to the Recents menu.
Available in OS X v10.3 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchWithoutActivationLaunch the application but do not bring it into the foreground.
Available in OS X v10.3 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchAsyncLaunch the application and return the results asynchronously.
Available in OS X v10.3 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchAllowingClassicStartupStart up the Classic compatibility environment, if it is required by the application.
Available in OS X v10.3 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchPreferringClassicForce the application to launch in the Classic compatibility environment.
Available in OS X v10.3 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchNewInstanceCreate a new instance of the application, even if one is already running.
Available in OS X v10.3 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchAndHideTell the application to hide itself as soon as it has finished launching.
Available in OS X v10.3 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchAndHideOthersHide all applications except the newly launched one.
Available in OS X v10.3 and later.
Declared in
NSWorkspace.h.NSWorkspaceLaunchDefaultLaunch the application asynchronously and launch it in the Classic environment, if required.
Available in OS X v10.3 and later.
Declared in
NSWorkspace.h.
Volume Mounting Notification User Info Keys
The following keys are available in the userInfo parameter of the notification named NSWorkspaceDidRenameVolumeNotification.
NSString * const NSWorkspaceVolumeLocalizedNameKey; NSString * const NSWorkspaceVolumeURLKey;
Constants
NSWorkspaceVolumeLocalizedNameKeyNSString containing the user-visible name of the volume.
Available in OS X v10.6 and later.
Declared in
NSWorkspace.h.NSWorkspaceVolumeURLKeyNSURLcontaining the mount path of the volume.Available in OS X v10.6 and later.
Declared in
NSWorkspace.h.
NSWorkspaceDidRenameVolumeNotification User Info Keys
The following keys are available in the userInfo parameter of the notification named NSWorkspaceDidRenameVolumeNotification.
NSString * const NSWorkspaceVolumeOldLocalizedNameKey; NSString * const NSWorkspaceVolumeOldURLKey;
Constants
NSWorkspaceVolumeOldLocalizedNameKeyNSStringcontaining the old user-visible name of the volumeAvailable in OS X v10.6 and later.
Declared in
NSWorkspace.h.NSWorkspaceVolumeOldURLKeyNSURLcontaining the old mount path of the volumeAvailable in OS X v10.6 and later.
Declared in
NSWorkspace.h.
NSWorkspaceApplicationKey User Info Key
This constant is supplied in the userInfo dictionary of various notifications.
NSString * const NSWorkspaceApplicationKey;
Constants
NSWorkspaceApplicationKeyThe value corresponding to this key is an instance of
NSRunningApplicationthat reflects the affected application.Available in OS X v10.6 and later.
Declared in
NSWorkspace.h.
Workspace icon creation options
These constants describe the NSWorkspaceIconCreationOptions values used by setIcon:forFile:options:. You can combine these using the C bitwise OR operator.
enum {
NSExcludeQuickDrawElementsIconCreationOption = 1 << 1,
NSExclude10_4ElementsIconCreationOption = 1 << 2
};
typedef NSUInteger NSWorkspaceIconCreationOptions;
Constants
NSExcludeQuickDrawElementsIconCreationOptionSuppress generation of the QuickDraw format icon representations that are used in OS X v10.0 through OS X v10.4.
Available in OS X v10.4 and later.
Declared in
NSWorkspace.h.NSExclude10_4ElementsIconCreationOptionSuppress generation of the new higher resolution icon representations that are supported in OS X v10.4.
Available in OS X v10.4 and later.
Declared in
NSWorkspace.h.
Notifications
All NSWorkspace notifications are posted to the NSWorkspace object’s own notification center, not the application’s default notification center. Access this center using the NSWorkspace object’s notificationCenter method.
NSWorkspaceWillLaunchApplicationNotification
The notification object is the shared NSWorkspace instance. In OS X v10.6 and later the userInfo dictionary contains the NSWorkspaceApplicationKey key with a corresponding instance of NSRunningApplication that represents the affected application.
In OS X v10.5 and earlier the userInfo dictionary contains the keys and values described in Table 1.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hNSWorkspaceDidLaunchApplicationNotification
The notification object is the shared NSWorkspace instance. In OS X v10.6 and later the userInfo dictionary contains the NSWorkspaceApplicationKey key with a corresponding instance of NSRunningApplication that represents the affected application.
In OS X v10.5 and earlier the userInfo dictionary contains the keys and values described in Table 1.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hNSWorkspaceDidTerminateApplicationNotification
The notification object is the shared NSWorkspace instance. In OS X v10.6 and later the userInfo dictionary contains the NSWorkspaceApplicationKey key with a corresponding instance of NSRunningApplication that represents the affected application.
In OS X v10.5 and earlier the userInfo dictionary contains the keys and values described in Table 1.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hNSWorkspaceSessionDidBecomeActiveNotification
The notification object is the shared NSWorkspace instance. The notification does not contain a userInfo dictionary.
Availability
- Available in OS X v10.3 and later.
Declared In
NSWorkspace.hNSWorkspaceSessionDidResignActiveNotification
The notification object is the shared NSWorkspace instance. The notification does not contain a userInfo dictionary.
If an application is launched in an inactive session, NSWorkspaceSessionDidResignActiveNotification is sent after NSApplicationWillFinishLaunchingNotification and before sending NSApplicationDidFinishLaunchingNotification.
Availability
- Available in OS X v10.3 and later.
Declared In
NSWorkspace.hNSWorkspaceDidHideApplicationNotification
The notification object is the shared NSWorkspace instance. In OS X v10.6 and later the userInfo dictionary contains the NSWorkspaceApplicationKey key with a corresponding instance of NSRunningApplication that represents the affected application.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hNSWorkspaceDidUnhideApplicationNotification
The notification object is the shared NSWorkspace instance. In OS X v10.6 and later the userInfo dictionary contains the NSWorkspaceApplicationKey key with a corresponding instance of NSRunningApplication that represents the affected application.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hNSWorkspaceDidActivateApplicationNotification
The notification object is the shared NSWorkspace instance. In OS X v10.6 and later the userInfo dictionary contains the NSWorkspaceApplicationKey key with a corresponding instance of NSRunningApplication that represents the affected application.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hNSWorkspaceDidDeactivateApplicationNotification
The notification object is the shared NSWorkspace instance. In OS X v10.6 and later the userInfo dictionary contains the NSWorkspaceApplicationKey key with a corresponding instance of NSRunningApplication that represents the affected application.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hNSWorkspaceDidRenameVolumeNotification
The notification object is the shared NSWorkspace instance. The userInfo dictionary contains keys in “NSWorkspaceDidRenameVolumeNotification User Info Keys” and “Volume Mounting Notification User Info Keys.”
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hNSWorkspaceDidMountNotification
The notification object is the shared NSWorkspace instance.
In OS X v10.5 and earlier the userInfo dictionary contains a key @"NSDevicePath" that returns the path where the device was mounted, as a string.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hNSWorkspaceWillUnmountNotification
This notification will not be delivered if a volume was forcibly and immediately made unavailable, such as when a FireWire drive is simply unplugged, because there is no chance to deliver it before the volume becomes unavailable.
The notification object is the shared NSWorkspace instance. The userInfo dictionary contains a key @"NSDevicePath" that returns the path where the device was mounted, as a string.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hNSWorkspaceDidUnmountNotification
This notification is delivered even if a volume was forcibly and immediately made unavailable, such as when a drive is simply unplugged.
The notification object is the shared NSWorkspace instance. The userInfo dictionary contains a key @"NSDevicePath" that returns the path where the device was mounted, as a string.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hNSWorkspaceDidPerformFileOperationNotification
The notification object is the shared NSWorkspace instance. The userInfo dictionary contains a key @"NSOperationNumber" with a NSNumber object containing an integer indicating the type of file operation
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hNSWorkspaceDidChangeFileLabelsNotification
The notification object is the shared NSWorkspace instance. The notification does not contain a userInfo dictionary.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hNSWorkspaceActiveSpaceDidChangeNotification
The notification object is the shared NSWorkspace instance. The notification does not contain a userInfo dictionary.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hNSWorkspaceDidWakeNotification
The notification object is the shared NSWorkspace instance. The notification does not contain a userInfo dictionary.
Availability
- Available in OS X v10.3 and later.
Declared In
NSWorkspace.hNSWorkspaceWillPowerOffNotification
The notification object is the shared NSWorkspace instance. This notification does not contain a userInfo dictionary.
Availability
- Available in OS X v10.0 and later.
Declared In
NSWorkspace.hNSWorkspaceWillSleepNotification
The notification object is the shared NSWorkspace instance. The notification does not contain a userInfo dictionary.
Availability
- Available in OS X v10.3 and later.
Declared In
NSWorkspace.hNSWorkspaceScreensDidSleepNotification
The notification object is the shared NSWorkspace instance. The notification does not contain a userInfo dictionary.
Few applications are likely to be interested in this notification, but they may be useful for certain hardware-based drawing decisions, for example when using OpenGL.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.hNSWorkspaceScreensDidWakeNotification
The notification object is the shared NSWorkspace instance. The notification does not contain a userInfo dictionary.
Few applications are likely to be interested in this notification, but they may be useful for certain hardware-based drawing decisions, for example when using OpenGL.
Availability
- Available in OS X v10.6 and later.
Declared In
NSWorkspace.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)