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-1999, 2001 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

> Standards:
> - MacOS-X
> - OpenStep
> - GNUstep

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.tiff' or 'foo.app/.dir.tiff'

If the folder was not an application wrapper, it just tries the.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.tiff";
       NSTypes = (
         {
           NSIcon = "tiff.tiff";
           NSUnixExtensions = ( tiff, tif );
         },
         {
           NSIcon = "xbm.tiff";
           NSUnixExtensions = ( xbm );
         }
       );
     }

Method summary

- -appIconForApp:
- -bundleForApp:
- -getBestAppInRole:forExtension:
- -getBestIconForExtension:
- -infoForExtension:
- -locateApplicationBinary:
- -setBestApp:inRole:forExtension:
- -setBestIcon:forExtension:
- +sharedWorkspace
- -activeApplication
- -checkForRemovableMedia
- -extendPowerOffBy:
- -fileSystemChanged
- -findApplications
- -fullPathForApplication:
- -getFileSystemInfoForPath:isRemovable:isWritable:isUnmountable:description:type:
- -getInfoForFile:application:type:
- -hideOtherApplications
- -iconForFile:
- -iconForFileType:
- -iconForFiles:
- -isFilePackageAtPath:
- -launchApplication:
- -launchApplication:showIcon:autolaunch:
- -launchedApplications
- -mountNewRemovableMedia
- -mountedLocalVolumePaths
- -mountedRemovableMedia
- -noteFileSystemChanged
- -noteFileSystemChanged:
- -noteUserDefaultsChanged
- -notificationCenter
- -openFile:
- -openFile:fromImage:at:inView:
- -openFile:withApplication:
- -openFile:withApplication:andDeactivate:
- -openTempFile:
- -openURL:
- -performFileOperation:source:destination:files:tag:
- -selectFile:inFileViewerRootedAtPath:
- -slideImage:from:to:
- -unmountAndEjectDeviceAtPath:
- -userDefaultsChanged

### sharedWorkspace

+ (NSWorkspace*) sharedWorkspace;

Description forthcoming.

### activeApplication

- (NSDictionary*) activeApplication;

Returns a description of the currently active application, containing the name (NSApplicationName), path (NSApplicationPath) and process identifier (NSApplicationProcessIdentifier).

### checkForRemovableMedia

- (void) checkForRemovableMedia;

Description forthcoming.

### extendPowerOffBy:

- (int) extendPowerOffBy: (int)requested;

Description forthcoming.

### fileSystemChanged

- (BOOL) fileSystemChanged;

Tracking Changes to the File System

### findApplications

- (void) findApplications;

Updates Registered Services, File Types, and other information about any applications installed in the standard locations.

### fullPathForApplication:

- (NSString*) fullPathForApplication: (NSString*)appName;

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;

Description forthcoming.

### getInfoForFile:application:type:

- (BOOL) getInfoForFile: (NSString*)fullPath application: (NSString**)appName type: (NSString**)type;

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;

Instructs all the other running applications to hide themselves. not yet implemented

### iconForFile:

- (NSImage*) iconForFile: (NSString*)fullPath;

Description forthcoming.

### iconForFileType:

- (NSImage*) iconForFileType: (NSString*)fileType;

Description forthcoming.

### iconForFiles:

- (NSImage*) iconForFiles: (NSArray*)pathArray;

Description forthcoming.

### isFilePackageAtPath:

- (BOOL) isFilePackageAtPath: (NSString*)fullPath;

Description forthcoming.

### launchApplication:

- (BOOL) launchApplication: (NSString*)appName;

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;

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;

Returns an array listing all the applications know to have been launched.

### mountNewRemovableMedia

- (NSArray*) mountNewRemovableMedia;

Description forthcoming.

### mountedLocalVolumePaths

- (NSArray*) mountedLocalVolumePaths;

Description forthcoming.

### mountedRemovableMedia

- (NSArray*) mountedRemovableMedia;

Description forthcoming.

### noteFileSystemChanged

- (void) noteFileSystemChanged;

Description forthcoming.

### noteFileSystemChanged:

- (void) noteFileSystemChanged: (NSString*)path;

Description forthcoming.

### noteUserDefaultsChanged

- (void) noteUserDefaultsChanged;

Simply makes a note that the user defaults database has changed.

### notificationCenter

- (NSNotificationCenter*) notificationCenter;

Returns the workspace notification center

### openFile:

- (BOOL) openFile: (NSString*)fullPath;

Description forthcoming.

### openFile:fromImage:at:inView:

- (BOOL) openFile: (NSString*)fullPath fromImage: (NSImage*)anImage at: (NSPoint)point inView: (NSView*)aView;

Description forthcoming.

### openFile:withApplication:

- (BOOL) openFile: (NSString*)fullPath withApplication: (NSString*)appName;

Description forthcoming.

### openFile:withApplication:andDeactivate:

- (BOOL) openFile: (NSString*)fullPath withApplication: (NSString*)appName andDeactivate: (BOOL)flag;

Description forthcoming.

### openTempFile:

- (BOOL) openTempFile: (NSString*)fullPath;

Description forthcoming.

### openURL:

- (BOOL) openURL: (NSURL*)url;

Description forthcoming.

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

- (BOOL) performFileOperation: (NSString*)operation source: (NSString*)source destination: (NSString*)destination files: (NSArray*)files tag: (int*)tag;

Description forthcoming.

### selectFile:inFileViewerRootedAtPath:

- (BOOL) selectFile: (NSString*)fullPath inFileViewerRootedAtPath: (NSString*)rootFullpath;

Description forthcoming.

### slideImage:from:to:

- (void) slideImage: (NSImage*)image from: (NSPoint)fromPoint to: (NSPoint)toPoint;

Animating an Image- slides it from one point on the screen to another.

### unmountAndEjectDeviceAtPath:

- (BOOL) unmountAndEjectDeviceAtPath: (NSString*)path;

Description forthcoming.

### userDefaultsChanged

- (BOOL) userDefaultsChanged;

Returns a flag to say if the defaults database has changed since the last time this method was called.

# Software documentation for the NSWorkspace(GNUstep) category

## NSWorkspace(GNUstep)

> Declared in:
>   AppKit/NSWorkspace.h

> Standards:
> - NotOpenStep
> - NotMacOS-X
> - GNUstep

Description forthcoming.

Method summary

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

### appIconForApp:

- (NSImage*) appIconForApp: (NSString*)appName;

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;

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;

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.

### getBestIconForExtension:

- (NSString*) getBestIconForExtension: (NSString*)ext;

Returns the path set for the icon matching the image by -setBestIcon:forExtension:

### infoForExtension:

- (NSDictionary*) infoForExtension: (NSString*)ext;

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.

### locateApplicationBinary:

- (NSString*) locateApplicationBinary: (NSString*)appName;

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;

Sets up a user preference for which app should be used to open files of the specified extension.

### setBestIcon:forExtension:

- (void) setBestIcon: (NSString*)iconPath forExtension: (NSString*)ext;

Sets up a user preference for which icon should be used to represent the specified file extension.

Up