Class

NSWorkspace

A workspace that can launch other apps and perform a variety of file-handling services.

Declaration

@interface NSWorkspace : NSObject

Overview

There is one shared NSWorkspace object per app. 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 app:

[[NSWorkspace sharedWorkspace] openFile:@"/Myfiles/README" withApplication:@"TextEdit"];

You can use the workspace object to:

  • Open, manipulate, and get information about files and devices.

  • Track changes to the file system, devices, and the user database.

  • Get and set Finder information for files.

  • Launch apps.

Legacy Constants

Table 1 describes keys for an NSDictionary object containing information about an app. This dictionary is returned by activeApplication and launchedApplications, and is also provided in the userInfo of NSWorkspace notifications for app launch and termination.

Note that these constants are considered legacy.

Table 1

Dictionary keys for launched and active apps

Key

Value

@"NSApplicationPath"

The full path to the app, as a NSString object.

@"NSApplicationName"

The app's name, as an NSString object.

@"NSApplicationBundleIdentifier"

The app’s bundle identifier, as an NSString object.

@"NSApplicationProcessIdentifier"

The app's process ID, as an NSNumber object.

@"NSApplicationProcessSerialNumberHigh"

The high long of the process serial number (PSN), as an NSNumber object.

@"NSApplicationProcessSerialNumberLow"

The low long of the process serial number (PSN), as an NSNumber object.

Topics

Accessing the Shared Workspace

sharedWorkspace

The shared workspace object.

Accessing the Workspace Notification Center

notificationCenter

The notification center for workspace notifications.

Opening URLs

- openURL:configuration:completionHandler:

Opens a URL asynchronously using the provided options.

- openURLs:withApplicationAtURL:configuration:completionHandler:

Opens one or more URLs asynchronously in the specified app using the provided options.

- openURL:

Opens the location at the specified URL.

Launching and Hiding Apps

- openApplicationAtURL:configuration:completionHandler:

Launches the app at the specified URL and asynchronously reports back on the app's status.

- hideOtherApplications

Hides all applications other than the sender.

Manipulating Files

- duplicateURLs:completionHandler:

Duplicates the specified URLS asynchronously in the same manner as the Finder.

- recycleURLs:completionHandler:

Moves the specified URLs to the trash in the same manner as the Finder.

- activateFileViewerSelectingURLs:

Activates the Finder, and opens one or more windows selecting the specified files.

- selectFile:inFileViewerRootedAtPath:

Selects the file at the specified path.

Manipulating Uniform Type Identifier Information

- typeOfFile:error:

Returns the uniform type identifier of the specified file, if it can be determined.

- localizedDescriptionForType:

Returns the localized description for the specified Uniform Type Identifier (UTI).

- preferredFilenameExtensionForType:

Returns the preferred filename extension for the specified Uniform Type Identifier (UTI).

- filenameExtension:isValidForType:

Returns whether the specified filename extension is appropriate for the Uniform Type Identifier (UTI).

- type:conformsToType:

Returns a Boolean indicating that the first Uniform Type Identifier (UTI) conforms to the second UTI.

- URLForApplicationWithBundleIdentifier:

Returns the URL for the app with the specified identifier.

Requesting Information

- getInfoForFile:application:type:

Retrieves information about the specified file.

- URLForApplicationToOpenURL:

Returns the URL to the default app that would be opened.

- getFileSystemInfoForPath:isRemovable:isWritable:isUnmountable:description:type:

Returns information about the file system at the specified path.

- isFilePackageAtPath:

Determines whether the specified path is a file package.

frontmostApplication

Returns the frontmost app, which is the app that receives key events.

runningApplications

Returns an array of running apps.

menuBarOwningApplication

Returns the app that owns the currently displayed menu bar.

Managing Icons

- iconForFile:

Returns an image containing the icon for the specified file.

- iconForFileType:

Returns an image containing the icon for files of the specified type.

- iconForFiles:

Returns an image containing the icon for the specified files.

- setIcon:forFile:options:

Sets the icon for the file or directory at the specified path.

NSWorkspaceIconCreationOptions

Constants that describe options for creating icons.

Unmounting a Device

- unmountAndEjectDeviceAtPath:

Unmounts and ejects the device at the specified path.

- unmountAndEjectDeviceAtURL:error:

Attempts to eject the volume mounted at the given path.

Managing the Desktop Image

- desktopImageURLForScreen:

Returns the URL for the desktop image for the given screen.

- setDesktopImageURL:forScreen:options:error:

Sets the desktop image for the given screen to the image at the specified URL.

- desktopImageOptionsForScreen:

Returns the desktop image options for the given screen.

NSWorkspaceDesktopImageOptionKey

Keys that indicate how to display a new desktop image.

Performing Finder Spotlight Searches

- showSearchResultsForQueryString:

Displays a Spotlight search results window in Finder for the specified query string.

Finder File Labels

fileLabels

The array of file labels, returned as strings.

fileLabelColors

The array of colors for the file labels.

Tracking Changes to the File System

- noteFileSystemChanged:

Informs the workspace object that the file system changed at the specified path.

Requesting Additional Time Before Logout

- extendPowerOffBy:

Requests the system wait for the specified amount of time before turning off the power or logging out the user.

Supporting Accessibility

accessibilityDisplayShouldDifferentiateWithoutColor

A Boolean value that indicates whether the app should avoid conveying information through color alone.

accessibilityDisplayShouldIncreaseContrast

A Boolean value that indicates whether the app should present a high contrast user interface.

accessibilityDisplayShouldReduceTransparency

A Boolean value that indicates whether the app should avoid using semitransparent backgrounds.

Performing Privileged Operations

- requestAuthorizationOfType:completionHandler:

Requests authorization to perform a privileged file operation.

NSWorkspaceAuthorization

The authorization granted to the app by the user.

NSWorkspaceAuthorizationType

The types of privileged file operations that can be authorized by the user.

Responding to Environment Notifications

The workspace posts notifications to its own notification center, not the app’s default notification center.

NSWorkspaceWillLaunchApplicationNotification

A notification that the workspace posts when the Finder is about to launch an app.

NSWorkspaceDidLaunchApplicationNotification

A notification that the workspace posts when a new app has started up.

NSWorkspaceDidTerminateApplicationNotification

A notification that the workspace posts when an app finishes executing.

NSWorkspaceSessionDidBecomeActiveNotification

A notification that the workspace posts after a user session is switched in.

NSWorkspaceSessionDidResignActiveNotification

A notification that the workspace posts before a user session is switched out.

NSWorkspaceDidHideApplicationNotification

A notification that the workspace posts when the Finder hid an app.

NSWorkspaceDidUnhideApplicationNotification

A notification that the workspace posts when the Finder unhid an app.

NSWorkspaceDidActivateApplicationNotification

A notification that the workspace posts when the Finder is about to activate an app.

NSWorkspaceDidDeactivateApplicationNotification

A notification that the workspace posts when the Finder deactivated an app.

NSWorkspaceDidRenameVolumeNotification

A notification that the workspace posts when a volume changes its name or mount path.

NSWorkspaceDidMountNotification

A notification that the workspace posts when a new device has been mounted.

NSWorkspaceWillUnmountNotification

A notification that the workspace posts when the Finder is about to unmount a device.

NSWorkspaceDidUnmountNotification

A notification that the workspace posts when the Finder unmounts a device.

NSWorkspaceDidChangeFileLabelsNotification

A notification that the workspace posts when the Finder file labels or colors change.

NSWorkspaceActiveSpaceDidChangeNotification

A notification that the workspace posts when a Spaces change occurs.

NSWorkspaceDidWakeNotification

A notification that the workspace posts when the machine wakes from sleep.

NSWorkspaceWillPowerOffNotification

A notification that the workspace posts when the user requests a logout or powers off the machine.

NSWorkspaceWillSleepNotification

A notification that the workspace posts before the machine goes to sleep.

NSWorkspaceScreensDidSleepNotification

A notification that the workspace posts when the machine’s screen goes to sleep.

NSWorkspaceScreensDidWakeNotification

A notification that the workspace posts when the machine’s screens wake.

NSWorkspaceAccessibilityDisplayOptionsDidChangeNotification

A notification that the workspace posts when any of the accessibility display options change.

NSWorkspaceVolumeLocalizedNameKey

A string containing the user-visible name of the volume.

NSWorkspaceVolumeURLKey

A URL containing the mount path of the volume.

NSWorkspaceVolumeOldLocalizedNameKey

A string containing the old user-visible name of the volume

NSWorkspaceVolumeOldURLKey

A URL containing the old mount path of the volume

Deprecated

Deprecated Symbols

Review unsupported symbols and their replacements.

Relationships

Inherits From

See Also

Environment

NSWorkspaceOpenConfiguration

The configuration options to use when opening URLs or launching apps.

NSAppKitVersion

Constants for determining which version of AppKit is available.