Class

NSWorkspace

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

Overview

There is one shared NSWorkspace object per app. You use the class method shared to access it. For example, the following statement uses an NSWorkspace object to request that a file be opened in the TextEdit app:

NSWorkspace.shared.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

userInfo dictionary keys for activeApplication and launchedApplications and notifications for app launch and termination

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 NSWorkspace Instance

class var shared: NSWorkspace

Returns the shared NSWorkspace instance.

Accessing the Workspace Notification Center

var notificationCenter: NotificationCenter

Returns the notification center for workspace notifications.

Manipulating Files

func duplicate([URL], completionHandler: (([URL : URL], Error?) -> Void)? = nil)

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

func recycle([URL], completionHandler: (([URL : URL], Error?) -> Void)? = nil)

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

func activateFileViewerSelecting([URL])

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

struct NSWorkspace.FileOperationName

These constants specify different types of file operations used by performFileOperation(_:source:destination:files:tag:).

Deprecated

Manipulating Uniform Type Identifier Information

func type(ofFile: String) -> String

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

func localizedDescription(forType: String) -> String?

Returns the localized description for the specified Uniform Type Identifier

func preferredFilenameExtension(forType: String) -> String?

Returns the preferred filename extension for the specified Uniform Type Identifier.

func filenameExtension(String, isValidForType: String) -> Bool

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

func type(String, conformsToType: String) -> Bool

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

func urlForApplication(withBundleIdentifier: String) -> URL?

Returns the URL for the app with the specified identifier.

Managing Icons

func icon(forFile: String) -> NSImage

Returns an image containing the icon for the specified file.

func icon(forFileType: String) -> NSImage

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

func icon(forFiles: [String]) -> NSImage?

Returns an image containing the icon for the specified files.

func setIcon(NSImage?, forFile: String, options: NSWorkspace.IconCreationOptions = []) -> Bool

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

struct NSWorkspace.IconCreationOptions

These constants describe the NSWorkspaceIconCreationOptions values used by setIcon(_:forFile:options:). You can combine these using the C bitwise OR operator.

Unmounting a Device

func unmountAndEjectDevice(atPath: String) -> Bool

Unmounts and ejects the device at the specified path.

func unmountAndEjectDevice(at: URL)

Attempts to eject the volume mounted at the given path.

Managing the Desktop Image

func desktopImageURL(for: NSScreen) -> URL?

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

func setDesktopImageURL(URL, for: NSScreen, options: [NSWorkspace.DesktopImageOptionKey : Any] = [:])

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

struct NSWorkspace.DesktopImageOptionKey

The following keys may be specified or returned in the options dictionary for setDesktopImageURL(_:for:options:).

Performing Finder Spotlight Searches

func showSearchResults(forQueryString: String) -> Bool

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

Finder File Labels

var fileLabelColors: [NSColor]

Returns the corresponding array of file label colors for the file labels.

var fileLabels: [String]

Returns the array of file labels as strings.

Tracking Changes to the File System

func noteFileSystemChanged(String)

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

Requesting Additional Time Before Logout

func extendPowerOff(by: Int) -> Int

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

Supporting Accessibility

var accessibilityDisplayShouldDifferentiateWithoutColor: Bool

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

var accessibilityDisplayShouldIncreaseContrast: Bool

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

var accessibilityDisplayShouldReduceTransparency: Bool

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

Notifications

All NSWorkspace notifications are posted to the NSWorkspace object’s own notification center, not the app’s default notification center. Access this center using the NSWorkspace object’s notificationCenter method.

class let willLaunchApplicationNotification: NSNotification.Name

Posted when the Finder is about to launch an app.

class let sessionDidResignActiveNotification: NSNotification.Name

Posted before a user session is switched out.

class let didActivateApplicationNotification: NSNotification.Name

Posted when the Finder is about to activate an app.

class let didRenameVolumeNotification: NSNotification.Name

Posted when a volume changes its name and/or mount path. These typically change simultaneously, in which case only one notification is posted.

class let didMountNotification: NSNotification.Name

Posted when a new device has been mounted.

class let willUnmountNotification: NSNotification.Name

Posted when the Finder is about to unmount a device.

class let didUnmountNotification: NSNotification.Name

Posted when the Finder did unmount a device.

class let didPerformFileOperationNotification: NSNotification.Name

Posted when a file operation has been performed in the receiving app.

Deprecated
class let didChangeFileLabelsNotification: NSNotification.Name

Posted when the Finder file labels or colors change.

class let didWakeNotification: NSNotification.Name

Posted when the machine wakes from sleep.

class let willPowerOffNotification: NSNotification.Name

Posted when the user has requested a logout or that the machine be powered off.

class let willSleepNotification: NSNotification.Name

Posted before the machine goes to sleep.

class let screensDidSleepNotification: NSNotification.Name

Posted when the machine’s screen goes to sleep.

class let screensDidWakeNotification: NSNotification.Name

Posted when the machine’s screens wake.

class let accessibilityDisplayOptionsDidChangeNotification: NSNotification.Name

Posted when any of the accessibility display options change.

Volume Mounting Notification User Info Keys

The following keys are available in the userInfo parameter of the notification named didRenameVolumeNotification.

NSWorkspaceDidRenameVolumeNotification User Info Keys

The following keys are available in the userInfo parameter of the notification named didRenameVolumeNotification.

Deprecated

func mountedRemovableMedia() -> [Any]?

Returns the full pathnames of all currently mounted removable disks.

Deprecated
func mountedLocalVolumePaths() -> [Any]?

Returns the mount points of all local volumes, not just the removable ones returned by mountedRemovableMedia().

Deprecated
func activeApplication() -> [AnyHashable : Any]?

Returns a dictionary with information about the current active app.

Deprecated
NSWorkspaceApplicationKey User Info Key

This constant is supplied in the userInfo dictionary of various notifications.

Relationships

Inherits From

Conforms To

See Also

Environment

AppKit Versions

Perform runtime checks to determine which version of AppKit is available.