NSDataLink

Inherits From: NSObject

Conforms To: NSCoding, NSCopying NSObject (NSObject)

Declared In: AppKit/NSDataLink.h

Class Description

An NSDataLink object (or data link) defines a single link between a selection in a source document and a dependent, dynamically updated selection in a destination document.

A data link is typically created when linkable data is copied to the pasteboard. First, an NSSelection object describing the data is created. Then a link to that selection is created using initLinkedToSourceSelection:managedBy:supportingTypes:. The link can then be written to the pasteboard using writeToPasteboard:. Usually, after the link has been written to the pasteboard (or saved to a file using writeToFile:) the link is freed because it's generally of no further use to the source application.

Once the data and link have been written to the pasteboard, they can be added to a destination document by an object that can respond to a message to Paste and Link. The object responding to this message will paste the data as usual. The destination application will then read the link from the pasteboard using initWithPasteboard:, create an NSSelection describing the linked data within the destination document, and will add the link by sending addLink:at: to the document's NSDataLinkManager object (also known as a data link manager or simply link manager).

When the link is added to the destination document's link manager, it becomes a destination link. At that time, the data link's object establishes a connection with the source document's link manager, which automatically creates a source link in the source application; the source link refers to the source selection.

A link that isn't managed by a link manager is a broken link. (Both source and destination links have link managers.) All links are broken links when they are created. Links can be explicitly broken (ensuring that they cause no updates) using the break method. Broken links (that aren't former source links) can be hooked up as destination links with the addLink:at: method. The disposition of a link (destination, source, or broken) can be retrieved with the disposition method. Most of the messages defined by the NSDataLink class can be sent to a link of any disposition, but some only make sense when sent to a link with a specific disposition; these are so noted in their method descriptions.

Links of all dispositions (except links to files) maintain an NSSelection object referring to the link's selection in the source document; this selection is returned by the sourceSelection method. Links directly to files represent entire files rather than selections in a document; these links are created with initLinkedToFile: and have no source selection.

Source and destination links also maintain an NSSelection describing the location of the data in the destination document; this selection is returned by the destinationSelection method.

See the NSSelection class description for more information on NSSelection objects.

Initializing a Link

• - (id)initLinkedToFile:(NSString *)filename Initializes a new instance corresponding to filename.
• - (id)initLinkedToSourceSelection:(NSSelection *)selection managedBy:(NSDataLinkManager *)linkManager supportingTypes:(NSArray *)newTypes Initializes a newly allocated instance corresponding to a selection in the source document selection. linkManager is the source document's link manager. newTypes is a set of types that linkManager's delegate is willing to provide when a destination of the link requests the data described by selection.
• - (id)initWithContentsOfFile:(NSString *)filename Initializes a new instance from filename.
• - (id)initWithPasteboard:(NSPasteboard *)pasteboard Initializes a new instance from pasteboard.

• - (BOOL)saveLinkIn:(NSString *)directoryName Saves the link in a filename provided by the user; the NSSavePanel's initial directory is in directoryName.
• - (BOOL)writeToFile:(NSString *)filename Writes the link into the file filename, returning NO if the file can't be written.
• - (void)writeToPasteboard:(NSPasteboard *)pasteboard Writes the link onto the pasteboard pasteboard.

• - (NSDataLinkDisposition)disposition Identifies the link's type.
• - (NSDataLinkNumber)linkNumber Returns the link's number.
• - (NSDataLinkManager *)manager Returns the link's manager.

• - (NSDate *)lastUpdateTime Returns the last time the link was updated.
• - (BOOL)openSource Opens the source document of the link and makes the source selection visible.
• - (NSString *)sourceApplicationName Returns the name of the application that owns the source document.
• - (NSString *)sourceFilename Returns the file name of the source document.
• - (NSSelection *)sourceSelection Returns the source selection.
• - (NSArray *)types Returns the types that the source document can provide.

• - (NSString *)destinationApplicationName Returns the name of the application that owns the destination document.
• - (NSString *)destinationFilename Returns the file name of the destination document.
• - (NSSelection *)destinationSelection Returns the destination selection.

• - (BOOL)break Breaks the link
• - (void)noteSourceEdited Informs a source link that the data referred to by its source selection has changed.
• - (void)setUpdateMode:(NSDataLinkUpdateMode)mode Sets the link's update mode to mode.
• - (BOOL)updateDestination Updates the data referred to by the link's destination selection with the contents referred to by the source selection.
• - (NSDataLinkUpdateMode)updateMode Returns the link's update mode.