Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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.

Exporting a Link

- (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.

Information about the Link

- (NSDataLinkDisposition)disposition	Identifies the link's type.

- (NSDataLinkNumber)linkNumber	Returns the link's number.

- (NSDataLinkManager *)manager	Returns the link's manager.

Information about the Link's Source

- (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.

Information about the Link's Destination

- (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.

Changing the Link

- (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.