Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

NXDataLinkManager

	Inherits From:	Object
	Conforms To:	NXSenderIsInvalid
	Declared In:	appkit/NXDataLinkManager.h

Class Description

An NXDataLinkManager manages data linked from and into a document.  If an application supports data linking, a data link manager should be instantiated for every document the application creates.  A data link manager must be assigned a delegate that assists it in keeping the document up-to-date; this delegate must implement some or all of the methods listed in the "Methods Implemented by the Delegate" section of this class specification.  In addition, the delegate must keep the link manager informed of the state of the document, sending it messages whenever the document is edited, saved, or otherwise altered.

Instance Variables

None declared in this class.

Method Types

Initializing and freeing a link manager

initWithDelegate: initWithDelegate:fromFile: free

Adding and removing links

addLink:at:

addLinkAsMarker:at: writeLinksToPasteboard: addLinkPreviouslyAt:fromPasteboard:at: breakAllLinks

Informing the link manager of document status

documentClosed documentEdited documentReverted documentSaved documentSavedAs: documentSavedTo:

Getting and setting information about the link manager

filename isEdited setLinksVerifiedByDelegate: areLinksVerifiedByDelegate delegate setInteractsWithUser: interactsWithUser

Getting and setting information about the manager's links

setLinkOutlinesVisible: areLinkOutlinesVisible findDestinationLinkWithSelection: prepareEnumerationState:forLinksOfType: nextLinkUsing:

Instance Methods

addLink:at:

addLink:(NXDataLink *)link at:(NXSelection *)selection

Adds the link link to the document, indicating that the data in the document described by selection is dependent upon the link. This method is invoked as part of the Paste and Link command to actually link in the data that was just pasted.  It can also be used at other times; for example, to link to files that are dragged into the document. This method makes link a destination link and sets selection as link's destination selection.  When the link's source is modified, the link manager's delegate will be sent a pasteFromPasteboard:at: or importFile:at: message with selection as an argument, indicating that the destination data must be updated. Returns self if the link is successfully added, nil if it isn't.  There are several situations that will result in failure to add the link, such as an inability to resolve the link to its source, so it's important to check the return value of this method and undo the requested operation if the linking fails.

addLinkAsMarker:at:

addLinkAsMarker:(NXDataLink *)link at:(NXSelection *)selection

Incorporates link into the document as a marker.  This method is used to implement link buttons that allow access to the link's source, but are never asked to receive data from the source document.  The link button in the destination document is described by selection.  This method adds the link and, upon success, sets its the link's update mode to NX_UpdateNever.  Returns self upon success, nil otherwise. The named images "NXLinkButton" and "NXLinkButtonH" can be used (through NXImage's findImageNamed: method) to represent ordinary and highlighted link buttons, respectively.  These images are shared, so you must copy them (using NXImage's copy method) if you need to scale them to a different size. See also:  addLink:at:

addLinkPreviouslyAt:fromPasteboard:at:

(NXDataLink *)addLinkPreviouslyAt:(NXSelection *)oldSelection

fromPasteboard:(Pasteboard *)pasteboard at:(NXSelection *)selection

Creates and adds a new destination link corresponding to the same source data as the link described by the destination selection oldSelection.  The new link's destination selection is provided in selection.  This method is useful if you paste data that is already linked.  It's similar to copying the old link and adding it using addLink:at:, except you specify the old destination selection rather than the old link.  Before invoking this method, the document's links must be written to the pasteboard pasteboard using writeLinksToPasteboard:.   Returns the new link if it's successfully added, or nil if the link can't be added or no link for oldSelection existed.

areLinkOutlinesVisible

(BOOL)areLinkOutlinesVisible

Used to inform the link manager's delegate of whether link outlines should be drawn around linked destination data.  When the delegate receives a dataLinkManagerRedrawLinkOutlines: message, it should query the link manager with an areLinkOutlinesVisible message.  If this message returns YES, the delegate should call the NXFrameLinkRect() function to draw a distinctive link outline around the dependent data. See also:  setLinkOutlinesVisible:

areLinksVerifiedByDelegate

(BOOL)areLinksVerifiedByDelegate

Return YES if the link manager's delegate will be asked to verify whether data based on the delegate's source links needs to be updated.  If so, the delegate should implement the dataLinkManager:isUpdateNeededForLink: method.  Returns NO by default, but the application can change this by sending the link manager a setLinksVerifiedByDelegate: message.

breakAllLinks

breakAllLinks

Breaks all the destination links in the document by sending each link a break message.  This method is typically invoked by the application's data link panel in response to user input.  Returns self. See also:  break (NXDataLink), pickedBreakAllLinks: (NXDataLinkPanel)

delegate

delegate

Returns the data link manager's delegate, the object that will be sent messages to provide source data, paste destination data, and help the data link manager keep links up-to-date. See also:  initWithDelegate:

documentClosed

documentClosed

An application should send this message to the link manager to inform it that the manager's document has been closed.  Returns self.

documentEdited

documentEdited

An application should send this message to the link manager to inform it that the manager's document has been edited.  If the delegate doesn't track source links individually, this method marks all source links as dirty, indicating that the dependent destination data will eventually need to be updated.  Returns self. See also:  dataLinkManagerTracksLinksIndividually: (NXDataLinkManager delegate)

documentReverted

documentReverted

An application should send this message to the link manager to inform it that the manager's document has been reverted to the last saved copy.  This method then restores the link manager and its links to their last saved state (from the last time the link manager received a documentSaved or documentSavedAs: message).  Returns self.

documentSaved

documentSaved

An application should send this message to the link manager to inform it that the manager's document has been saved.  This method stores the document's destination links and, if necessary, initiates updates of other documents dependent upon the document's source links.  Returns self.

documentSavedAs:

documentSavedAs:(const char *)path

An application should send this message to the link manager to inform it that the manager's document has been saved as the file specified by the full pathname path.  This method stores the document's destination links.  It also discards the manager's source links, since the documents for those links are not dependent upon the newly saved file.  Returns self.

documentSavedTo:

documentSavedTo:(const char *)path

An application should send this message to the link manager to inform it that a copy of the manager's document has been saved to the file specified by the full pathname path.  This method stores the appropriate link information along with the file, and returns self.

filename

(const char *)filename

Returns the name of the file for the link manager's document.  This is the name that was set with the initWithDelegate:fromFile: or documentSavedAs: method.

findDestinationLinkWithSelection:

(NXDataLink *)findDestinationLinkWithSelection:(NXSelection *)destSel

Returns the destination link for the selection destSel, or nil if the document has no link for that selection.  This method will tell you if the given selection is linked to a source.

free

free

Notifies the link managers of dependent documents that the link manager is going away, and frees the objects and storage held by the link manager.

init

init

There is no need to call this method; use one of the other init... methods to initialize a newly allocated NXDataLinkManager instance for a new document. See also:  initWithDelegate:fromFile:

initWithDelegate:

initWithDelegate:anObject

Initializes and returns a newly allocated NXDataLinkManager instance for a new document.  The link manager's delegate, specified by anObject, will be expected to provide source data, paste destination data, and help the data link manager keep links up-to-date.  Before data in the document can be linked to, the document will have to be saved and the link manager will have to be informed of the document's name by a documentSavedAs: message. See also:  initWithDelegate:fromFile:

initWithDelegate:fromFile:

initWithDelegate:anObject fromFile:(const char *)path

Initializes a newly allocated NXDataLinkManager instance for a new document.  The link manager's delegate, specified by anObject, will be expected to to provide source data, paste destination data, and help the data link manager keep links up-to-date.  The document's file is specified by the full path path.  The file must exist or initialization will fail. See "Methods Implemented by the Delegate" at the end of this class specification for information about the methods the delegate should implement to assist the link manager. Returns the new link manager upon success; frees the allocated storage and returns nil if initialization fails. See also:  initWithDelegate:fromFile:

interactsWithUser

(BOOL)interactsWithUser

Returns YES if the link manager should display alert panels when problems with links occur, NO if the displays are to be suppressed.  This value is set with the setInteractsWithUser: method; the default value is YES.

isEdited

(BOOL)isEdited

Returns YES if the document has been edited since the last save, or NO if the file for the document is up-to-date.  The document's edited state is set by the documentEdited method, and cleared by documentSaved and related methods.

nextLinkUsing:

(NXDataLink *)nextLinkUsing:(NXLinkEnumerationState *)state

Returns the link manager's next link based on state.  state must be initially prepared using prepareEnumerationState:forLinksOfType: to allow the caller to retrieve each of the application's destination or source links in turn.  This method return nil if there are no more links.

prepareEnumerationState:forLinksOfType:

prepareEnumerationState:(NXLinkEnumerationState *)state

forLinksOfType:(NXDataLinkDisposition)srcOrDest

Prepares the variable indicated by state to allow the application to retrieve each of the link manager's links, one at a time, with later invocations of nextLinkUsing:.  srcOrDest must be either NX_LinkInDestination or NX_LinkInSource to indicate whether the nextLinkUsing: method is to return the next destination link or the next source link, respectively.  Returns self if there is one or more links of the requested type, or nil if there is none.

setInteractsWithUser:

setInteractsWithUser:(BOOL)flag

Instructs the link manager as to whether it should display alert panels when problems with links occur.  If flag is YES (the default value), alert panels will be displayed.  Returns self. See also:  interactsWithUser

setLinkOutlinesVisible:

setLinkOutlinesVisible:(BOOL)flag

Sets the internal flag indicating to the link manager's delegate whether link outlines ought to be displayed; this value can be returned by areLinkOutlinesVisible. If the link manager's delegate implements the dataLinkManagerRedrawLinkOutlines: method, this message will be sent to the delegate and it should either display link outlines using NXFrameLinkRect() or erase link outlines if they were previously displayed, based on the return value of areLinkOutlinesVisible. Returns self.

setLinksVerifiedByDelegate:

setLinksVerifiedByDelegate:(BOOL)flag

Sets whether the update status of links will be individually verified by the link manager's delegate.  If flag is YES, the delegate must implement the dataLinkManager:isUpdateNeededForLink: method to tell the link manager if data based on a source link needs to be updated. By default, the update status of an individual link isn't verified by the delegate, so the link manager verifies a link based on its last update time.  An example where this verification could be incorrect might be a link to a database query; if the query itself doesn't change, the link manager might return that data is up-to-date, even though the database referred to by the query might have changed. See also:  areLinksVerifiedByDelegate

writeLinksToPasteboard:

writeLinksToPasteboard:(Pasteboard *)pasteboard

Writes all the link manager's links to the pasteboard pasteboard in preparation for an invocation of addLinkPreviouslyAt:fromPasteboard:at:, which will expect to find one link matching its specified selection. The links are written with Pasteboard's addTypes:num:owner: method, which doesn't change the pasteboard's owner or change count, using a private pasteboard type.

Methods Implemented by the Delegate

copyToPasteboard:at:cheapCopyAllowed:

copyToPasteboard:(Pasteboard *)pasteboard

at:(NXSelection *)selection cheapCopyAllowed:(BOOL)flag

Implemented by the link manager's delegate to supply the source data described by selection on the pasteboard pasteboard. selection was previously provided by the application when it created an NXDataLink using initLinkedToSourceSelection:managedBy:supportingTypes:count:. Since the Pasteboard works lazily, the delegate doesn't have to provide all data representations at this time; it simply has to declare the pasteboard types it's willing to provide for selection.  Normally, the delegate must put at least one representation on the pasteboard in order to generate any of the specified types when one is requested.  However, if flag is YES, the system guarantees that no events will be processed by the application before the delegate is requested to provide the specified data; in this case, the application doesn't necessarily have to write any data representations to the pasteboard.  This method should return self upon success, or nil if the selection can't be resolved. See also:  pasteFromPasteboard:at: (NXDataLinkManager delegate), declareTypes:num:owner: (Pasteboard), pasteboard:provideData: (Pasteboard owner)

createSelection

(NXSelection *)createSelection

Never invoked by the system.

dataLinkManager:didBreakLink:

dataLinkManager:(NXDataLinkManager *)sender

didBreakLink:(NXDataLink *)link

If this method is implemented by the delegate, it will be invoked to inform the delegate that the destination link link was broken and thus data based on link's destination selection will no longer be updated. The link shouldn't be be sent a free message at this time, because the method that invoked dataLinkManager:didBreakLink: may still reference the link.  However, the link can be freed with Application's delayedFree: method.  Alternatively, the link could be kept around for a while in order to allow the break operation to be undone; if this is requested, the link could be re-added with addLink:at:. See also:  break (NXDataLink), destinationSelection (NXDataLink)

dataLinkManager:isUpdateNeededForLink:

(BOOL)dataLinkManager:(NXDataLinkManager *)sender

isUpdateNeededForLink:(NXDataLink *)link

A delegate that sends a setLinksVerifiedByDelegate: message to the link manager (indicating that the update status for individual links will be verified by the delegate) should implement this method and return YES if the source data identified by link's source selection has been modified since the link's last update time. See also:  lastUpdateTime (NXDataLink)

dataLinkManager:startTrackingLink:

dataLinkManager:(NXDataLinkManager *)sender

startTrackingLink:(NXDataLink *)link

Informs the delegate that another document has established a data link to the link manager's document.  The delegate need only implement this method if it returns YES in response to a dataLinkManagerTracksLinksIndividually: message.  link is a newly added source link; the data that it applies to is identified by link's source selection. See also:  dataLinkManagerTracksLinksIndividually:

dataLinkManager:stopTrackingLink:

dataLinkManager:(NXDataLinkManager *)sender

stopTrackingLink:(NXDataLink *)link

Informs the delegate that the former source link link is no longer linked to the document.  There are many reasons that a link might be removed; the destination document could get closed, the link could be explicitly broken, or the destination application might have died. See also:  dataLinkManagerTracksLinksIndividually:

dataLinkManagerCloseDocument:

dataLinkManagerCloseDocument:(NXDataLinkManager *)sender

Never invoked by the system.

dataLinkManagerDidEditLinks:

dataLinkManagerDidEditLinks:(NXDataLinkManager *)sender

Informs the delegate that link data has been modified.  Since the link data is stored alongside the document's data and should be considered part of the document, the delegate should use this notification to mark the document as edited.

dataLinkManagerRedrawLinkOutlines:

dataLinkManagerRedrawLinkOutlines:(NXDataLinkManager *)sender

If the delegate implements this method, it will be invoked any time the manager is instructed to show or hide link outlines through setLinkOutlinesVisible:.  This method should query the link manager with areLinkOutlinesVisible to find out if link outlines should be displayed.  If so, it should invoke NXFrameLinkRect() to draw a distinctive outline around the linked data; otherwise it should display the data without outlines.

dataLinkManagerTracksLinksIndividually:

(BOOL)dataLinkManagerTracksLinksIndividually:

(NXDataLinkManager *)sender

If the delegate implements this method it should return whether it's willing to track links individually.  If the delegate doesn't implement this method, links are not individually tracked.  If the delegate implements this method and returns YES, it should also implement dataLinkManager:startTrackingLink: and dataLinkManager:stopTrackingLink: to follow the links in use. Many applications do not need to track links individually, but there are several situations where it can be useful to know when a link is used.  For example, the delegate may want to individually track links in order to continually update destination documents each time data for a link's source selection is modified; an individual link can be sent an updateDestination message whenever a modification is made that affects the destination. Additionally, many links may be placed on the pasteboard when data is copied, but few of those links will actually ever get used.  If the application must store selection-state information in the document, it should only do so for selections (and their associated links) that actually get used; this method is used to find out if the delegate wants to be informed when a link gets used.

importFile:at:

importFile:(const char *)filename at:(NXSelection *)selection

If the application has added a link based on an entire file (that is, used addLink:at: to incorporate a link created by initLinkedToFile:), the delegate must implement this method to import the filename file at the destination described by selection.  This method should return self upon success, or nil if the selection can't be resolved.

pasteFromPasteboard:at:

pasteFromPasteboard:(Pasteboard *)pasteboard at:(NXSelection *)selection

If the application has added an ordinary destination link (that is, used addLink:at: to incorporate a link created by initFromPasteboard: or a related method), the delegate must implement this method to paste the updated data that has been made available on the pasteboard.  The destination for the data is described by selection, which was supplied to the link manager as an argument to the addLink:at: method. The data is read from the pasteboard just as it is for any ordinary paste; see the Pasteboard class specification for more information on reading data from a pasteboard.  This method should return self upon success, or nil if the selection can't be resolved.

setSelection:

setSelection:(NXSelection *)selection

Never invoked by the system.

showSelection:

showSelection:(NXSelection *)selection

In an application that serves as a link source, the delegate should implement this method to show the source data for the specified selection selection.  This method should scroll the document so the selected data is visible.  It might additionally highlight the selected data using the function NXFrameLinkRect() with the argument isDestination set to NO.  This method should return self upon success, or nil if the selection can't be resolved.

windowForSelection:

windowForSelection:(NXSelection *)selection

In an application that serves as a link source, the delegate should implement this method to return the Window object for the given selection, or nil if the selection can't be resolved.