Up

# NSWorkspace

### Authors

Scott Christley (`scottc@net-community.com`)
Richard Frith-Macdonald (`richard@brainstorm.co.uk`)
Fred Kiefer (`FredKiefer@gmx.de`)

> Workspace class

Copyright: (C) 1996-2010 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSWorkspace class
2. Software documentation for the NSWorkspace(GNUstep) category

# Software documentation for the NSWorkspace class

## NSWorkspace : NSObject

> Declared in:
>   AppKit/NSWorkspace.h

Availability: OpenStep

The NSWorkspace class gathers together a large number of capabilities needed for workspace management.

The make_services tool examines all applications (anything with a.app,.debug, or.profile suffix) in the system, local, and user Apps directories, and caches information about the services each app provides (extracted from the Info-gnustep.plist file in each application).

In addition to the cache of services information, it builds a cache of information about all known applications (including information about file types they handle).

NSWorkspace reads the cache and uses it to determine which application to use to open a document and which icon to use to represent that document.

The NSWorkspace API has been extended to provide methods for finding/setting the preferred icon/application for a particular file type. NSWorkspace will use the 'best' icon/application available.

To determine the executable to launch, if there was an Info-gnustep.plist/Info.plist in the app wrapper and it had an NSExecutable field - it uses that name. Otherwise, it tries to use the name of the app - eg. foo.app/foo
The executable is launched by NSTask, which handles the addition of machine/os/library path components as necessary.

To determine the icon for a file, it uses the value from the cache of icons for the file extension, or use an 'unknown' icon.

To determine the icon for a folder, if the folder has a '.app', '.debug' or '.profile' extension - the Info-gnustep.plist file is examined for an 'NSIcon' value and NSWorkspace tries to use that. If there is no value specified - it tries 'foo.app/foo.png' or 'foo.app/foo.tiff' or 'foo.app/.dir.png' or 'foo.app/.dir.tiff'

If the folder was not an application wrapper, it just tries the.dir.png and.dir.tiff file.

If no icon was available, it uses a default folder icon or a special icon for the root directory.

The information about what file types an app can handle needs to be stored in Info-gnustep.plist in an array keyed on the name NSTypes, within which each value is a dictionary.

In the NSTypes fields, NSWorkspace uses NSIcon (the icon to use for the type) NSUnixExtensions (a list of file extensions corresponding to the type) and NSRole (what the app can do with documents of this type Editor, Viewer, or None). In the AppList cache, make_services generates a dictionary, keyed by file extension, whose values are the dictionaries containing the NSTypes dictionaries of each of the apps that handle the extension. The NSWorkspace class makes use of this cache at runtime.

If the Info-gnustep.plist of an application says that it can open files with a particular extension, then when NSWorkspace is asked to open such a file it will attempt to send an -application:openFile: message to the application (which must be handled by the applications delegate). If the application is not running, NSWorkspace will instead attempt to launch the application passing the filename to open after a '-GSFilePath' flag in the command line arguments. For a GNUstep application, the application will recognize this and invoke the -application:openFile: method passing it the file name.

This command line argument mechanism provides a way for non-gnustep applications to be used to open files simply by provideing a wrapper for them containing the appropriate Info-gnustep.plist.
For instance - you could set up xv.app to contain a shellscript 'xv' that would start the real xv binary passing it a file to open if the '-GSFilePath' argument was given. The Info-gnustep.plist file could look like this:

     {
       NSExecutable = "xv";
       NSIcon = "xv.png";
       NSTypes = (
         {
           NSIcon = "tiff.tiff";
           NSUnixExtensions = (tiff, tif);
         },
         {
           NSIcon = "xbm.tiff";
           NSUnixExtensions = (xbm);
         }
    );
     }

Instance Variables
Method summary

- -appIconForApp:
- -bundleForApp:
- -getBestAppInRole:forExtension:
- -getBestAppInRole:forScheme:
- -getBestIconForExtension:
- -infoForExtension:
- -infoForScheme:
- -locateApplicationBinary:
- -setBestApp:inRole:forExtension:
- -setBestApp:inRole:forScheme:
- -setBestIcon:forExtension:
- +sharedWorkspace
- -absolutePathForAppBundleWithIdentifier:
- -activeApplication
- -checkForRemovableMedia
- -extendPowerOffBy:
- -fileSystemChanged
- -filenameExtension:isValidForType:
- -findApplications
- -fullPathForApplication:
- -getFileSystemInfoForPath:isRemovable:isWritable:isUnmountable:description:type:
- -getInfoForFile:application:type:
- -hideOtherApplications
- -iconForFile:
- -iconForFileType:
- -iconForFiles:
- -isFilePackageAtPath:
- -launchAppWithBundleIdentifier:options:additionalEventParamDescriptor:launchIdentifier:
- -launchApplication:
- -launchApplication:showIcon:autolaunch:
- -launchedApplications
- -localizedDescriptionForType:
- -mountNewRemovableMedia
- -mountedLocalVolumePaths
- -mountedRemovableMedia
- -noteFileSystemChanged
- -noteFileSystemChanged:
- -noteUserDefaultsChanged
- -notificationCenter
- -openFile:
- -openFile:fromImage:at:inView:
- -openFile:withApplication:
- -openFile:withApplication:andDeactivate:
- -openTempFile:
- -openURL:
- -openURLs:withAppBundleIdentifier:options:additionalEventParamDescriptor:launchIdentifiers:
- -performFileOperation:source:destination:files:tag:
- -preferredFilenameExtensionForType:
- -selectFile:inFileViewerRootedAtPath:
- -setIcon:forFile:options:
- -slideImage:from:to:
- -type:conformsToType:
- -typeOfFile:error:
- -unmountAndEjectDeviceAtPath:
- -userDefaultsChanged

### sharedWorkspace

+ (NSWorkspace*) sharedWorkspace;
Availability: OpenStep
Description forthcoming.

### absolutePathForAppBundleWithIdentifier:

- (NSString*) absolutePathForAppBundleWithIdentifier: (NSString*)bundleIdentifier;
Availability: MacOS-X 10.3.0
Description forthcoming.

### activeApplication

- (NSDictionary*) activeApplication;
Availability: MacOS-X 10.2.0
Returns a description of the currently active application, containing the name (NSApplicationName), path (NSApplicationPath) and process identifier (NSApplicationProcessIdentifier).
Returns `nil` if there is no known active application.

### checkForRemovableMedia

- (void) checkForRemovableMedia;
Availability: OpenStep
Description forthcoming.

### extendPowerOffBy:

- (int) extendPowerOffBy: (int)requested;
Availability: OpenStep
Description forthcoming.

### fileSystemChanged

- (BOOL) fileSystemChanged;
Availability: OpenStep
Tracking Changes to the File System

### filenameExtension: isValidForType:

- (BOOL) filenameExtension: (NSString*)filenameExtension isValidForType: (NSString*)typeName;
Availability: MacOS-X 10.5.0
Description forthcoming.

### findApplications

- (void) findApplications;
Availability: OpenStep
Updates Registered Services, File Types, and other information about any applications installed in the standard locations.

### fullPathForApplication:

- (NSString*) fullPathForApplication: (NSString*)appName;
Availability: OpenStep
Given an application name, return the full path for that application.
This method looks for the application in standard locations, and if not found there, according to MacOS-X documentation, returns `nil`.
If the supplied application name is an absolute path, returns that path irrespective of whether such an application exists or not. This is not the docmented debavior in the MacOS-X documentation, but is the MacOS-X implemented behavior.
If the appName has an extension, it is used, otherwise in GNUstep the standard app, debug, and profile extensions * are tried.

### getFileSystemInfoForPath: isRemovable: isWritable: isUnmountable: description: type:

- (BOOL) getFileSystemInfoForPath: (NSString*)fullPath isRemovable: (BOOL*)removableFlag isWritable: (BOOL*)writableFlag isUnmountable: (BOOL*)unmountableFlag description: (NSString**)description type: (NSString**)fileSystemType;
Availability: OpenStep
Description forthcoming.

### getInfoForFile: application: type:

- (BOOL) getInfoForFile: (NSString*)fullPath application: (NSString**)appName type: (NSString**)type;
Availability: OpenStep
This method gets information about the file at fullPath and returns `YES` on success, `NO` if the named file could not be found.
On success, the name of the preferred application for opening the file is returned in *appName, or `nil` if there is no known application to open it.
The returned value in *type describes the file using one of the following constants.

NSPlainFileType
  A plain file or a directory that some application claims to be able to open like a file.
NSDirectoryFileType
  An untyped directory
NSApplicationFileType
  A GNUstep application
NSFilesystemFileType
  A file system mount point
NSShellCommandFileType
  Executable shell command

### hideOtherApplications

- (void) hideOtherApplications;
Availability: OpenStep
Instructs all the other running applications to hide themselves. not yet implemented

### iconForFile:

- (NSImage*) iconForFile: (NSString*)fullPath;
Availability: OpenStep
Description forthcoming.

### iconForFileType:

- (NSImage*) iconForFileType: (NSString*)fileType;
Availability: OpenStep
Description forthcoming.

### iconForFiles:

- (NSImage*) iconForFiles: (NSArray*)pathArray;
Availability: OpenStep
Description forthcoming.

### isFilePackageAtPath:

- (BOOL) isFilePackageAtPath: (NSString*)fullPath;
Availability: MacOS-X 10.0.0
Description forthcoming.

### launchAppWithBundleIdentifier: options: additionalEventParamDescriptor: launchIdentifier:

- (BOOL) launchAppWithBundleIdentifier: (NSString*)bundleIdentifier options: (NSWorkspaceLaunchOptions)options additionalEventParamDescriptor: (NSAppleEventDescriptor*)descriptor launchIdentifier: (NSNumber**)identifier;
Availability: MacOS-X 10.3.0
Description forthcoming.

### launchApplication:

- (BOOL) launchApplication: (NSString*)appName;
Availability: OpenStep
Calls -launchApplication:showIcon:autolaunch: with arguments set to show the icon but not set it up as an autolaunch.

### launchApplication: showIcon: autolaunch:

- (BOOL) launchApplication: (NSString*)appName showIcon: (BOOL)showIcon autolaunch: (BOOL)autolaunch;
Availability: OpenStep

Launches the specified application (unless it is already running).
If the autolaunch flag is yes, sets the autolaunch user default for the newly launched application, so that applications which understand the concept of being autolaunched at system startup time can modify their behavior appropriately.

Sends an NSWorkspaceWillLaunchApplicationNotification before it actually attempts to launch the application (this is not sent if the application is already running).

The application sends an NSWorkspaceDidlLaunchApplicationNotification on completion of launching. This is not sent if the application is already running, or if it fails to complete its startup.

Returns `NO` if the application cannot be launched (eg. it does not exist or the binary is not executable).

Returns `YES` if the application was already running or of it was launched (this does not necessarily mean that the application succeeded in starting up fully).

Once an application has fully started up, you should be able to connect to it using [NSConnection +rootProxyForConnectionWithRegisteredName:host:] passing the application name (normally the filesystem name excluding path and file extension) and an empty host name. This will let you communicate with the the [NSApplication -delegate] of the launched application, and you can generally use this as a test of whether an application is running correctly.

### launchedApplications

- (NSArray*) launchedApplications;
Availability: MacOS-X 10.2.0
Returns an array listing all the applications known to have been launched. Each entry in the array is a dictionary providing the name, path and process identfier of an application.

### localizedDescriptionForType:

- (NSString*) localizedDescriptionForType: (NSString*)typeName;
Availability: MacOS-X 10.5.0
Description forthcoming.

### mountNewRemovableMedia

- (NSArray*) mountNewRemovableMedia;
Availability: OpenStep
Description forthcoming.

### mountedLocalVolumePaths

- (NSArray*) mountedLocalVolumePaths;
Availability: MacOS-X 10.0.0
Description forthcoming.

### mountedRemovableMedia

- (NSArray*) mountedRemovableMedia;
Availability: OpenStep
Description forthcoming.

### noteFileSystemChanged

- (void) noteFileSystemChanged;
Availability: OpenStep
Description forthcoming.

### noteFileSystemChanged:

- (void) noteFileSystemChanged: (NSString*)path;
Availability: MacOS-X 10.0.0
Description forthcoming.

### noteUserDefaultsChanged

- (void) noteUserDefaultsChanged;
Availability: OpenStep
Simply makes a note that the user defaults database has changed.

### notificationCenter

- (NSNotificationCenter*) notificationCenter;
Availability: OpenStep
Returns the workspace notification center

### openFile:

- (BOOL) openFile: (NSString*)fullPath;
Availability: OpenStep
Description forthcoming.

### openFile: fromImage: at: inView:

- (BOOL) openFile: (NSString*)fullPath fromImage: (NSImage*)anImage at: (NSPoint)point inView: (NSView*)aView;
Availability: OpenStep
Description forthcoming.

### openFile: withApplication:

- (BOOL) openFile: (NSString*)fullPath withApplication: (NSString*)appName;
Availability: OpenStep
Description forthcoming.

### openFile: withApplication: andDeactivate:

- (BOOL) openFile: (NSString*)fullPath withApplication: (NSString*)appName andDeactivate: (BOOL)flag;
Availability: OpenStep
Description forthcoming.

### openTempFile:

- (BOOL) openTempFile: (NSString*)fullPath;
Availability: OpenStep
Description forthcoming.

### openURL:

- (BOOL) openURL: (NSURL*)url;
Availability: MacOS-X 10.0.0
Description forthcoming.

### openURLs: withAppBundleIdentifier: options: additionalEventParamDescriptor: launchIdentifiers:

- (BOOL) openURLs: (NSArray*)urls withAppBundleIdentifier: (NSString*)bundleIdentifier options: (NSWorkspaceLaunchOptions)options additionalEventParamDescriptor: (NSAppleEventDescriptor*)descriptor launchIdentifiers: (NSArray**)identifiers;
Availability: MacOS-X 10.3.0
Description forthcoming.

### performFileOperation: source: destination: files: tag:

- (BOOL) performFileOperation: (NSString*)operation source: (NSString*)source destination: (NSString*)destination files: (NSArray*)files tag: (int*)tag;
Availability: OpenStep
Description forthcoming.

### preferredFilenameExtensionForType:

- (NSString*) preferredFilenameExtensionForType: (NSString*)typeName;
Availability: MacOS-X 10.5.0
Description forthcoming.

### selectFile: inFileViewerRootedAtPath:

- (BOOL) selectFile: (NSString*)fullPath inFileViewerRootedAtPath: (NSString*)rootFullpath;
Availability: OpenStep
Description forthcoming.

### setIcon: forFile: options:

- (BOOL) setIcon: (NSImage*)image forFile: (NSString*)fullPath options: (NSWorkspaceIconCreationOptions)options;
Availability: MacOS-X 10.3.0
Description forthcoming.

### slideImage: from: to:

- (void) slideImage: (NSImage*)image from: (NSPoint)fromPoint to: (NSPoint)toPoint;
Availability: OpenStep
Animating an Image- slides it from one point on the screen to another.

### type: conformsToType:

- (BOOL) type: (NSString*)firstTypeName conformsToType: (NSString*)secondTypeName;
Availability: MacOS-X 10.5.0
Description forthcoming.

### typeOfFile: error:

- (NSString*) typeOfFile: (NSString*)absoluteFilePath error: (NSError**)outError;
Availability: MacOS-X 10.5.0
Description forthcoming.

### unmountAndEjectDeviceAtPath:

- (BOOL) unmountAndEjectDeviceAtPath: (NSString*)path;
Availability: OpenStep
Description forthcoming.

### userDefaultsChanged

- (BOOL) userDefaultsChanged;
Availability: OpenStep
Returns a flag to say if the defaults database has changed since the last time this method was called.

## Instance Variables for NSWorkspace Class

### _fileSystemChanged

@protected BOOL _fileSystemChanged;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _iconMap

@protected NSMutableDictionary* _iconMap;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _launched

@protected NSMutableDictionary* _launched;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _userDefaultsChanged

@protected BOOL _userDefaultsChanged;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _workspaceCenter

@protected NSNotificationCenter* _workspaceCenter;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the NSWorkspace(GNUstep) category

## NSWorkspace(GNUstep)

> Declared in:
>   AppKit/NSWorkspace.h

Availability: Not in OpenStep/MacOS-X
Description forthcoming.
Method summary

- -appIconForApp:
- -bundleForApp:
- -getBestAppInRole:forExtension:
- -getBestAppInRole:forScheme:
- -getBestIconForExtension:
- -infoForExtension:
- -infoForScheme:
- -locateApplicationBinary:
- -setBestApp:inRole:forExtension:
- -setBestApp:inRole:forScheme:
- -setBestIcon:forExtension:

### appIconForApp:

- (NSImage*) appIconForApp: (NSString*)appName;
Availability: Not in OpenStep/MacOS-X
Returns the application icon for the given app. Or null if none defined or appName is not a valid application name.

### bundleForApp:

- (NSBundle*) bundleForApp: (NSString*)appName;
Availability: Not in OpenStep/MacOS-X
Returns the application bundle for the named application. Accepts either a full path to an app or just the name. The extension (.app,.debug, .profile) is optional, but if provided it will be used.
Returns `nil` if the specified app does not exist as requested.

### getBestAppInRole: forExtension:

- (NSString*) getBestAppInRole: (NSString*)role forExtension: (NSString*)ext;
Availability: Not in OpenStep/MacOS-X
Returns the 'best' application to open a file with the specified extension using the given role . If the role is `nil` then apps which can edit are preferred but viewers are also acceptable. Uses a user preferred app or picks any good match.

### getBestAppInRole: forScheme:

- (NSString*) getBestAppInRole: (NSString*)role forScheme: (NSString*)scheme;
Availability: Not in OpenStep/MacOS-X
Returns the 'best' application to open a file with the specified URL scheme using the given role. If the role is `nil` then apps which can edit are preferred but viewers are also acceptable. Uses a user preferred app or picks any good match.

### getBestIconForExtension:

- (NSString*) getBestIconForExtension: (NSString*)ext;
Availability: Not in OpenStep/MacOS-X
Returns the path set for the icon matching the image by -setBestIcon:forExtension:

### infoForExtension:

- (NSDictionary*) infoForExtension: (NSString*)ext;
Availability: Not in OpenStep/MacOS-X
Gets the applications cache (generated by the make_services tool) and looks up the special entry that contains a dictionary of all file extensions recognised by GNUstep applications. Then finds the dictionary of applications that can handle our file and returns it.

### infoForScheme:

- (NSDictionary*) infoForScheme: (NSString*)scheme;
Availability: Not in OpenStep/MacOS-X
Gets the applications cache (generated by the make_services tool) and looks up the special entry that contains a dictionary of all URL schemes recognised by GNUstep applications. Then finds the dictionary of applications that can handle our scheme and returns it.

### locateApplicationBinary:

- (NSString*) locateApplicationBinary: (NSString*)appName;
Availability: Not in OpenStep/MacOS-X
Requires the path to an application wrapper as an argument, and returns the full path to the executable.

### setBestApp: inRole: forExtension:

- (void) setBestApp: (NSString*)appName inRole: (NSString*)role forExtension: (NSString*)ext;
Availability: Not in OpenStep/MacOS-X
Sets up a user preference for which app should be used to open files of the specified extension.

### setBestApp: inRole: forScheme:

- (void) setBestApp: (NSString*)appName inRole: (NSString*)role forScheme: (NSString*)scheme;
Availability: Not in OpenStep/MacOS-X
Sets up a user preference for which app should be used to open files of the specified URL scheme

### setBestIcon: forExtension:

- (void) setBestIcon: (NSString*)iconPath forExtension: (NSString*)ext;
Availability: Not in OpenStep/MacOS-X
Sets up a user preference for which icon should be used to represent the specified file extension.

Up