Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java


[Previous] [Class List] [Next]

NSWorkspace


Inherits from: NSObject
Package: com.apple.yellow.application

Inherits from: NSObject
Conforms to: NSObject
(NSObject)
Declared in: AppKit/NSWorkspace.h




Class Description


An NSWorkspace object responds to application requests to perform a variety of services:

There is one shared NSWorkspace object per application. You use the class method sharedWorkspace to access it.

On the Microsoft Windows platform, some of the methods in this class have no effect. Refer to the method descriptions below.


Constants

These constants specify different types of file:


Constant Description
PlainFileType Plain (untyped) file
DirectoryFileType Directory
ApplicationFileType OpenStep application
FilesystemFileType File system mount point
ShellCommandFileType Executable shell command

The constants specify different type of file operations. They're used by performFileOperation.


Constant Description
MoveOperation Move file to destination
CopyOperation Copy file to destination
LinkOperation Create link to file in destination
CompressOperation Compress file
DecompressOperation Decompress file
EncryptOperation Encrypt file
DecryptOperation Decrypt file
DestroyOperation Destroy file
RecycleOperation Move file to recycler
DuplicateOperation Duplicate file in source directory

Method Types


Accessing the shared NSWorkspace
sharedWorkspace
Accessing the NSWorkspace notification center
notificationCenter
Opening files
openFile:
openFile:withApplication:
openFile:withApplication:andDeactivate:
openTempFile
Manipulating applications
launchApplication:
launchApplication:showIcon:autolaunch:
hideOtherApplications
Manipulating files
performFileOperation
selectFile
Requesting information about files
iconForFile
iconForFileType
iconForFiles
getInfoForFile:application:type:
fullPathForApplication
getFileSystemInfoForPath:isRemovable:isWritable:isUnmountable:description:type:
Requesting additional time before logout
extendPowerOffBy
Tracking changes to the file system
noteFileSystemChanged
fileSystemChanged
Updating registered services and file types
findApplications
Tracking changes to the defaults database
noteUserDefaultsChanged
userDefaultsChanged
Tracking status changes for applications and devices
mountedRemovableMedia
mountNewRemovableMedia
checkForRemovableMedia
Animating an image
slideImage
Unmounting a device
unmountAndEjectDeviceAtPath

Static Methods



sharedWorkspace

public static NSWorkspace sharedWorkspace()

Returns the shared NSWorkspace instance.


Instance Methods



applicationForFile

public String applicationForFile(String aString)

<<Description Forthcoming>>

checkForRemovableMedia

public void checkForRemovableMedia()

On the Mach platform, polls the system's drives for any disks that have been inserted but not yet mounted. checkForRemovableMedia doesn't wait until such disks are mounted; instead, it requests that the disk be mounted asynchronously and returns immediately.

This method has no effect on the Microsoft Windows platform.

See Also: mountNewRemovableMedia, mountedRemovableMedia



extendPowerOffBy

public int extendPowerOffBy(int requested)

Requests requested milliseconds more time before the power goes off or the user logs out. Returns the number of additional milliseconds granted. On some platforms you might not be able to extend the time.

fileSystemChanged

public boolean fileSystemChanged()

On the Mach platform, returns true if a change to the file system has been registered with a noteFileSystemChanged message since the last fileSystemChanged message; false otherwise.

This method is not implemented on the Microsoft Windows platform. If you try to use it, it throws an exception.



findApplications

public void findApplications()

On the Mach platform, examines all applications in the normal places (/Network/Applications, /System/Applications, /System/Developer/Applications) and updates the records of registered services and file types.

This method has no effect on the Microsoft Windows platform.



fullPathForApplication

public String fullPathForApplication(String appName)

Returns the full path for the application appName, or null if appName isn't in one of the normal places.

hideOtherApplications

public void hideOtherApplications()

Hides all applications other than the sender. This method has no effect on the Microsoft Windows platform. On the Mach platform, the user can hide all applications except the current one by Command-double-clicking an application's tile, so programmatic invocation of this method is usually unnecessary.

iconForFile

public NSImage iconForFile(String fullPath)

Returns an NSImage with the icon for the single file specified by fullPath.

See Also: getInfoForFile:application:type:iconForFileType, iconForFiles



iconForFileType

public NSImage iconForFileType(String fileType)

Returns an NSImage with the icon for the file type specified by fileType.

See Also: iconForFile, iconForFiles



iconForFiles

public NSImage iconForFiles(NSArray fullPaths)

Returns an NSImage with the icon for the files specified in fullPaths, an array of NSStrings. If fullPaths specifies one file, its icon is returned. If fullPaths specifies more than one file, an icon representing the multiple selection is returned.

See Also: iconForFile, iconForFileType


launchApplication

public boolean launchApplication(String appName, boolean showIcon, boolean autoLaunch)

Launches the application appName. If showIcon is false, the application's icon won't be placed on the screen. (The icon still exists, though.) If autolaunch is true, the autolaunch default will be set as though the application were autolaunched at startup. This method is provided to enable daemon-like applications that lack a normal user interface and for use by alternative dock programs. Its use is not generally encouraged.

Returns true if the application is successfully launched or already running, and false if it can't be launched.

Before this method begins, it posts an NSWorkspaceWillLaunchApplicationNotification to the NSWorkspace's notification center. When the operation is complete, it posts an NSWorkspaceDidLaunchApplicationNotification.

public boolean launchApplication(String appName)

Launches the application appName. appName need not be specified with a full path and, in the case of an application wrapper, can be specified with or without the .app extension. Returns true if the application is successfully launched or already running, false if it can't be launched.

Before this method begins, it posts an NSWorkspaceWillLaunchApplicationNotification to the NSWorkspace's notification center. When the operation is complete, it posts an NSWorkspaceDidLaunchApplicationNotification.


mountNewRemovableMedia

public NSArray mountNewRemovableMedia()

On the Mach platform, polls the system's drives for any disks that have been inserted but not yet mounted, waits until the new disks have been mounted, and returns an NSArray of NSStrings containing full pathnames to all newly mounted disks. This method posts an NSWorkspaceDidMountNotification to the NSWorkspace's notification center when it is finished.

This method is not implemented on the Microsoft Windows platform. If you try to use it, it throws an exception.

See Also: checkForRemovableMedia, mountedRemovableMedia



mountedRemovableMedia

public NSArray mountedRemovableMedia()

Returns an NSArray of NSStrings containing the full pathnames of all currently mounted removable disks. This method is not implemented on the Microsoft Windows platform. If you try to use it, it throws an exception.

On the Mach platform, if the computer provides an interrupt or other notification when the user inserts a disk into a drive, the Workspace Manager will mount the disk immediately. However, if no notification is given, the Workspace Manager won't be aware that a disk needs to be mounted. On such systems, an application should invoke either mountNewRemovableMedia or checkForRemovableMedia before invoking mountedRemovableMedia. Either of these methods cause the Workspace Manager to poll the drives to see if a disk is present. If a disk has been inserted but not yet mounted, these methods will cause the Workspace Manager to mount it.

The Disk button in an Open or Save panel invokes mountedRemovableMedia and mountNewRemovableMedia as part of its operation, so most applications won't need to invoke these methods directly.

See Also: checkForRemovableMedia, mountNewRemovableMedia



noteFileSystemChanged

public void noteFileSystemChanged()

On the Mach platform, informs NSWorkspace that the file system has changed. NSWorkspace 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.

This method has no effect on the Microsoft Windows platform.

See Also: fileSystemChanged



noteUserDefaultsChanged

public void noteUserDefaultsChanged()

On the Mach platform, informs NSWorkspace that the defaults database has changed. NSWorkspace then reads all the defaults it is interested in and reconfigures itself appropriately. For example, on Mach platforms, this method is used by the Preferences application to notify Workspace Manager whether the user prefers to see hidden files.

This method has no effect on the Microsoft Windows platform.

See Also: userDefaultsChanged



notificationCenter

public NSNotificationCenter notificationCenter()

Returns the notification center for workspace notifications.

openFile

public boolean openFile(String fullPath, String appName, boolean flag)

Opens the file specified by fullPath using the appName application. appName need not be specified with a full path and, in the case of an application wrapper, can be specified with or without the .app extension. <<There are no longer any cases of applications *without* application wrappers, and haven't been since NEXTSTEP 2.0. Should probably delete this conditional.>> If appName is null, the default application for the file's type is used. If flag is true, the sending application is deactivated before the request is sent, allowing the opening application to become the active application. Returns true if the file is successfully opened, false otherwise.

public boolean openFile(String fullPath, String appName)

Opens the file specified by fullPath using the appName application. appName need not be specified with a full path and, in the case of an application wrapper, can be specified with or without the .app extension. <<There are no longer any cases of applications *without* application wrappers, and haven't been since NEXTSTEP 2.0. Should probably delete this conditional.>> The sending application is deactivated before the request is sent. Returns true if the file is successfully opened, false otherwise.

public boolean openFile(String fullPath, NSImage anImage, NSPoint point, NSView aView)

Opens the file specified by fullPath using the default application for its type. On the Mach platform, Workspace Manager provides 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 aView's coordinates. <<Is this still true with the brave new more Macintosh look and feel?>> On the Microsoft Windows platform, this method is the same as the openFile method that takes only a fullPath argument.

The sending application is deactivated before the request is sent. Returns true if the file is successfully opened, false otherwise.

public boolean openFile(String fullPath)

Opens the file specified by fullPath using the default application for its type; returns true if the file was successfully opened, false otherwise. The sending application is deactivated before the request is sent.


openTempFile

public boolean openTempFile(String fullPath)

Opens the temporary file specified by fullPath using the default application for its type. The sending application is deactivated before the request is sent. Using this method instead of one of the openFile:... methods lets the receiving application know that it should delete the file when it no longer needs it. Returns true if the file is successfully opened, false otherwise.

See Also: openFile:openFile:withApplication:openFile:withApplication:andDeactivate:



performFileOperation

public int performFileOperation(String operation, String source, String destination, NSArray files)

Performs a file operation on a set of files in a particular directory. operation is some file operation, such as compressing or moving files. files contains NSString specifying the names of the files to be manipulated. The file names are given relative to the source directory. The list can contain both files and directories; all of them must be located directly within source (not in one of its subdirectories).

Some operations-such as moving, copying, and linking files-require a destination directory to be specified. If not, destination should be the empty string ("").

The possible values for operation are:


Operation Meaning
MoveOperation Move file to destination
CopyOperation Copy file to destination
LinkOperation Create link to file in destination
CompressOperation Compress file
DecompressOperation Decompress file
EncryptOperation Encrypt file
DecryptOperation Decrypt file
DestroyOperation Destroy file
RecycleOperation Move file to recycler
DuplicateOperation Duplicate file in source directory

NSWorkspaceCompressOperation, NSWorkspaceDecompressOperation, NSWorkspaceEncryptOperation, and NSWorkspaceDecryptOperation are not available on the Microsoft Windows platform.

This method returns a negative integer if the operation fails, 0 if the operation is performed synchronously and succeeds, and a positive integer if the operation is performed asynchronously. The positive integer is a tag that identifies the requested file operation. Before this method returns, it posts an NSWorkspaceDidPerformFileOperationNotification to NSWorkspace's notification center.



selectFile

public boolean selectFile(String fullPath, String rootFullPath)

Selects the file specified by fullPath. If a path is specified by rootFullPath, a new file viewer is opened. If rootFullPath is an empty string (""), the file is selected in the main viewer. Returns true if the file is successfully selected, false otherwise.

slideImage

public void slideImage(NSImage image, NSPoint fromPoint, NSPoint toPoint)

On Mach platforms, animates a sliding image of image from fromPoint to toPoint, specified in screen coordinates. This method has no effect on the Microsoft Windows platform.

unmountAndEjectDeviceAtPath

public boolean unmountAndEjectDeviceAtPath(String path)

Unmounts and ejects the device at path. Returns true if the unmount operation succeeded, false otherwise. When this method begins, it posts an NSWorkspaceWillUnmountNotification to NSWorkspace's notification center. When it is finished, it posts an NSWorkspaceDidUnmountNotification.

userDefaultsChanged

public boolean userDefaultsChanged()

On the Mach platform, returns whether a change to the defaults database has been registered with a noteUserDefaultsChanged message since the last userDefaultsChanged message.

This method has no effect on the Microsoft Windows platform.





Notifications


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

NSWorkspaceDidLaunchApplicationNotification

Posted when a new application has started up.

This notification contains a notification object and a userInfo dictionary. The notification object is the shared NSWorkspace instance. The userInfo dictionary contains these keys and values:


Key Value
NSApplicationName The application being terminated

NSWorkspaceDidMountNotification

Posted when a new device has been mounted.

This notification contains a notification object and a userInfo dictionary. The notification object is the shared NSWorkspace instance. The userInfo dictionary contains these keys and values:


Key Value
NSDevicePath The path where the device was mounted

NSWorkspaceDidPerformFileOperationNotification

Posted when a file operation has been performed.

This notification contains a notification object and a userInfo dictionary. The notification object is the shared NSWorkspace instance. The userInfo dictionary contains these keys and values:


Key Value
NSOperationNumber A number indicating the type of file operation completed

NSWorkspaceDidTerminateApplicationNotification

Posted when an application finishes executing.

This notification contains a notification object and a userInfo dictionary. The notification object is the shared NSWorkspace instance. The userInfo dictionary contains these keys and values:


Key Value
NSApplicationName The application that terminated

NSWorkspaceDidUnmountNotification

Posted when the workspace has unmounted a device.

This notification contains a notification object and a userInfo dictionary. The notification object is the shared NSWorkspace instance. The userInfo dictionary contains these keys and values:


Key Value
NSDevicePath The path where the device was previously mounted

NSWorkspaceWillLaunchApplicationNotification

Posted when the workspace is about to launch an application.

This notification contains a notification object and a userInfo dictionary. The notification object is the shared NSWorkspace instance. The userInfo dictionary contains these keys and values:


Key Value
NSApplicationName The application about to be launched

NSWorkspaceWillPowerOffNotification

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

This notification contains a notification object but no userInfo dictionary. The notification object is the shared NSWorkspace instance.

NSWorkspaceWillUnmountNotification

Posted when the workspace is about to unmount a device.

This notification contains a notification object and a userInfo dictionary. The notification object is the shared NSWorkspace instance. The userInfo dictionary contains these keys and values:


Key Value
NSDevicePath The path where the device is mounted



[Previous] [Next]