Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
NSFileWrapper
| Inherits from | |
| Implements | |
| Package | com.apple.cocoa.application |
| Companion guide |
Overview
An NSFileWrapper holds a file’s contents in dynamic memory. In this role it enables a document object to embed a file, treating it as a unit of data that can be displayed as an image (and possibly edited in place), saved to disk, or transmitted to another application. It can also store an icon for representing the file in a document or in a dragging operation.
Tasks
Constructors
Writing to a File or Serializing
Checking a File Wrapper’s Type
Setting Attributes
-
setFilename
-
filename
-
setPreferredFilename
-
preferredFilename
-
setIcon
-
icon
-
setFileAttributes
-
fileAttributes
Updating
Modifying a Directory Wrapper
-
addFileWrapper
-
removeFileWrapper
-
addFileWithPath
-
addRegularFileWithContents
-
addSymbolicLinkWithDestination
-
fileWrappers
-
keyForFileWrapper
Inspecting a Regular File Wrapper
Inspecting a Link Wrapper
Constructors
NSFileWrapper
Creates an empty NSFileWrapper.
public NSFileWrapper()
Creates a new NSFileWrapper, based on symLink.
public NSFileWrapper(String path, boolean symLink)
Discussion
If symLink is true, the NSFileWrapper is a link wrapper pointing to path. The new file wrapper has no filename or associated disk representation until you save it using writeToFile. It’s also initialized with open permissions; anyone can read or write the disk representations it saves.
If symLink is false, the NSFileWrapper is initialized with the file or directory at path, setting its type to regular file, directory, or link wrapper based on the type of that file and caching the file’s attributes. Also sets the wrapper’s preferred filename and recorded filename to the last component of path. If path identifies a directory, this method recursively creates file wrappers for each file or directory within that directory.
Creates a new NSFileWrapper based on serialized.
public NSFileWrapper(NSData data, boolean serialized)
Discussion
If serialized is true, the NSFileWrapper is initialized with data, setting its type to regular file, directory, or link wrapper based on the nature of that data and reading the file attributes from the data as well. data is a serialized representation of a file’s or directory’s contents in the format used for the pasteboard type NSPasteboard.FileContentsPboardType. Data of this format is returned by such methods as serializedRepresentation or NSAttributedString’s RTFFromRange.
The new file wrapper has no filename or associated disk representation until you save it using writeToFile.
If serialized is false, the NSFileWrapper is initialized as a regular file wrapper with data. The new file wrapper has no filename or associated disk representation until you save it using writeToFile. It’s also initialized with open permissions; anyone can read or write the disk representations that it saves.
Creates a new NSFileWrapper as a directory wrapper containing wrappers.
public NSFileWrapper(NSDictionary aDictionary)
Discussion
The new directory wrapper has no filename or associated disk representation until you save it using writeToFile. It’s also initialized with open permissions; anyone can read, write, or change directory to the disk representations that it saves.
If any file wrapper in wrappers doesn’t have a preferred name, its preferred name is automatically set to its corresponding dictionary key in wrappers.
Instance Methods
addFileWithPath
Adds a new file wrapper to the receiving directory wrapper.
public String addFileWithPath(String path)
Discussion
Initializes the new file wrapper using path , then adds the new file wrapper by invoking addFileWrapper. Returns the dictionary key used for the newly added file wrapper within the directory wrapper. Throws an InternalInconsistencyException if sent to a regular file or link wrapper.
See Also
addFileWrapper
Adds wrapper to the receiving directory wrapper.
public String addFileWrapper(NSFileWrapper wrapper)
Discussion
Returns the dictionary key used for wrapper within the directory wrapper. Throws an InternalInconsistencyException if sent to a regular file or link wrapper or an InvalidArgumentException if wrapper doesn’t have a preferred name (set using setPreferredFilename).
See Also
-
addFileWithPath -
addRegularFileWithContents -
addSymbolicLinkWithDestination -
removeFileWrapper -
fileWrappers
addRegularFileWithContents
Adds a new regular file wrapper to the receiving directory wrapper.
public String addRegularFileWithContents(NSData contents, String filename)
Discussion
Initializes the new file wrapper using contents, sets its preferred name with setPreferredFilename using filename as the argument, then adds the new file wrapper by invoking addFileWrapper. Returns the dictionary key used for the newly added file wrapper within the directory wrapper. Throws an InternalInconsistencyException if sent to a regular file or link wrapper or an InvalidArgumentException if filename is null or empty.
See Also
addSymbolicLinkWithDestination
Adds a new link wrapper to the receiving directory wrapper.
public String addSymbolicLinkWithDestination(String path, String filename)
Discussion
Initializes the new link wrapper , sets its preferred name with setPreferredFilename using filename as the argument, then adds the new link wrapper by invoking addFileWrapper. Returns the dictionary key used for the newly added link wrapper within the directory wrapper. Throws an InternalInconsistencyException if sent to a regular file or link wrapper or an InvalidArgumentException if filename is null or empty.
See Also
fileAttributes
Returns the file attributes last read from disk or set using setFileAttributes.
public NSDictionary fileAttributes()
Discussion
These attributes are used whenever the file wrapper is saved using writeToFile. See NSPathUtilities for information on the contents of the attributes dictionary.
filename
Returns the filename for the last known disk representation of the receiver, or null if the receiver has no filename.
public String filename()
Discussion
The filename is used for record-keeping purposes only and is set automatically when the file wrapper is created from disk and when it’s saved to a disk using writeToFile (although this method allows you to request that the filename not be updated).
See Also
fileWrappers
Returns the file wrappers contained in a directory wrapper.
public NSDictionary fileWrappers()
Discussion
Throws an InternalInconsistencyException if sent to a regular file or link wrapper. See “Working With Directory Wrappers” for information on the dictionary.
See Also
icon
Returns an image that can be used to represent the file wrapper to the user, or null if the file wrapper has none.
public NSImage icon()
Discussion
You don’t have to use this image; for example, a file viewer typically looks up icons automatically based on file extensions, and so wouldn’t need this image. Similarly, if a file wrapper represents an image file, you can display the image directly rather than a file icon.
See Also
isDirectory
Returns true if the receiver is a directory wrapper, false otherwise.
public boolean isDirectory()
See Also
isRegularFile
Returns true if the receiver is a regular file wrapper, false otherwise.
public boolean isRegularFile()
See Also
isSymbolicLink
Returns true if the receiver is a link wrapper, false otherwise.
public boolean isSymbolicLink()
See Also
keyForFileWrapper
Returns the key by which the receiving directory wrapper stores wrapper in its dictionary (as returned by the fileWrappers method).
public String keyForFileWrapper(NSFileWrapper wrapper)
Discussion
This key is not necessarily the filename for wrapper. Throws an InternalInconsistencyException if sent to a regular file or link wrapper.
See Also
needsToBeUpdatedFromPath
Returns true if the receiver’s contents on disk may have changed, false otherwise.
public boolean needsToBeUpdatedFromPath(String path)
Discussion
For a regular file wrapper, whether contents have changed is determined by comparing the modification time and access permissions of the file or directory at path against those of the receiver. For a link wrapper, whether contents have changed is determined by checking whether the destination path has changed (not by checking the modification time or access attributes of the destination). For a directory, whether contents have changed is determined as needed recursively for each file wrapper contained in the directory; added or removed files also count as changes.
See Also
preferredFilename
Returns the file wrapper’s preferred filename.
public String preferredFilename()
Discussion
This name is used as the default dictionary key and filename when a file wrapper is added to a directory wrapper. However, if another file wrapper with the same preferred name already exists in the directory wrapper when the receiver is added, the dictionary key and filename assigned may differ from the preferred filename.
See Also
regularFileContents
Returns the contents of the receiving regular file wrapper.
public NSData regularFileContents()
Discussion
Throws an InternalInconsistencyException if sent to a directory or link wrapper.
removeFileWrapper
Removes wrapper from the receiving directory wrapper and releases it.
public void removeFileWrapper(NSFileWrapper wrapper)
Discussion
Throws an InternalInconsistencyException if sent to a regular file or link wrapper.
See Also
-
addFileWithPath -
addFileWrapper -
addRegularFileWithContents -
addSymbolicLinkWithDestination -
fileWrappers
serializedRepresentation
Returns the receiver’s contents as an opaque collection of data, in the format used for the pasteboard type NSPasteboard.FileContentsPboardType.
public NSData serializedRepresentation()
setFileAttributes
Sets the file attributes applied whenever the file wrapper is saved using writeToFile to attributes.
public void setFileAttributes(NSDictionary attributes)
Discussion
See NSPathUtilities for information on the contents of the attributes dictionary.
See Also
setFilename
Sets the filename for the disk representation of the receiver to filename.
public void setFilename(String filename)
Discussion
The filename is used for record-keeping purposes only and is set automatically when the file wrapper is saved to a disk using writeToFile (although this method allows you to request that the filename not be updated). You should rarely need to invoke this method.
Throws an InvalidArgumentException if filename is null or empty.
See Also
setIcon
Sets the image that can be used to represent the file wrapper to the user to anImage.
public void setIcon(NSImage anImage)
Discussion
You don’t have to use this image; for example, a file viewer typically looks up icons automatically based on file extensions and so wouldn’t need this image. Similarly, if a file wrapper represents an image file, you can display the image directly rather than a file icon.
See Also
setPreferredFilename
Sets the receiver’s preferred filename to filename.
public void setPreferredFilename(String filename)
Discussion
This name is used as the default dictionary key and filename when a file wrapper is added to a directory wrapper. However, if another file wrapper with the same preferred name already exists in the directory wrapper when the receiver is added, the dictionary key and filename assigned may differ from the preferred filename. Throws an InvalidArgumentException if filename is null or empty.
See Also
symbolicLinkDestination
Returns the actual path represented by the receiving link wrapper.
public String symbolicLinkDestination()
Discussion
Throws InternalInconsistencyException if sent to a regular file or directory wrapper.
updateFromPath
Rereads the file wrapper’s information from the file or directory at path, including contents or link destination, icon, and file attributes.
public boolean updateFromPath(String path)
Discussion
For a directory wrapper, the contained file wrappers are also sent updateFromPath messages. If files in the directory on disk have been added or removed, corresponding file wrappers are released or created as needed. Returns true if updating actually occurred, false if it wasn’t necessary.
See Also
writeToFile
Writes the receiver’s contents to a file or directory at path.
public boolean writeToFile(String path, boolean atomicFlag, boolean updateNamesFlag)
Discussion
Returns true on success and false on failure. If atomicFlag is true, attempts to write the file safely so that an existing file at path is not overwritten, nor does a new file at path actually get created, unless the write is successful. If updateNamesFlag is true and the contents are successfully written, changes the receiver’s filename to the last component of path, and the filenames of any children of a directory wrapper to the filenames under which they’re written to disk.
If you’re executing a Save or Save As operation, pass true for updateNamesFlag; if you’re executing a Save To operation, pass false for updateNamesFlag.
See Also
© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)