initFromFile:Copyright ©1995 by NeXT Computer, Inc. All Rights Reserved.
| NXDataLink |
| Inherits From: | Object | |
| Declared In: | appkit/NXDataLink.h |
| Class Description |
| An NXDataLink defines a single data 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 NXSelection object describing the data is created. Then a link to that selection is created using initLinkedToSourceSelection:managedBy:supportingTypes:count:. 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 is 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 using the Paste and Link command. The implementation responding to this command will paste the data as usual (with the possible exception that the linked data will be pasted in a "display" format rather than a richer, editable format, since the data is to be dependent on the source data rather than fundamentally editable). The destination application will then read the link from the pasteboard using initFromPasteboard:, create an NXSelection describing the linked data within the destination document, and will add the link by sending addLink:at: to the document's link manager. When the link is added to the destination document's link manager, it becomes a destination link. At this time, the data links implementation 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. Only applications that must update destination links continuously need to be aware of when source links are created; these applications can return YES in response to a dataLinkManagerTracksLinksIndividually: message, and then respond to dataLinkManager:startTrackingLink: messages to receive notifications that source links are created. 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 NXDataLink 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 NXSelection 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 NXSelection describing how the data is presented in the destination document; this selection is returned by the destinationSelection method. |
| Instance Variables |
| None declared in this class. |
| Method Types |
| Initializing a link | initFromFile: |
| initFromPasteboard: initLinkedToFile: initLinkedToSourceSelection:managedBy: |
| supportingTypes:count: |
| copyFromZone: |
| Exporting a link | writeToPasteboard: |
| saveLinkIn: writeToFile: |
| Information about the link | manager |
| disposition linkNumber |
| Information about the link's source |
| sourceAppName sourceFilename sourceSelection openSource lastUpdateTime types |
| Information about the link's destination |
| destinationAppName destinationFilename destinationSelection |
| Updating the link's data | sourceEdited |
| updateDestination setUpdateMode: updateMode break |
| Instance Methods |
| break |
| break |
| Breaks the link so the data referred to by its selection will not get updated. The link is removed from its link manager and its destination selection is freed. The link itself is not freed; if it wasn't formerly a source link it can be hooked back up again using NXDataLinkManager's addLink:at: method. Alternatively, it can be explicitly freed by the application if the application directly sent the break message, or freed by Applications's delayedFree: method on receiving a dataLinkManager:didBreakLink: notification that the link was broken. (This could happen in response to user input from the data link panel.) Returns self if sent to a destination link, does nothing and returns nil if sent to a broken link If sent to a source link, the message is forwarded to the destination link; it then returns self if the link is successfully broken and nil otherwise. |
| copyFromZone: |
| copyFromZone:(NXZone *)zone |
| Returns a copy of the receiving data link allocated from zone. The copy is essentially linked to the source data, but not hooked up to the destination document. The copy has a copy of the receiver's source selection, has no destination selection, and its disposition is NX_LinkBroken.
See also: |
| destinationAppName |
| (const char *)destinationAppName |
| Returns the name (as returned by Application's appName method) of the application containing the destination link.
See also: |
| destinationFilename |
| (const char *)destinationFilename |
| Returns the file name of the destination document, as set by any of several NXDataLinkManager methods for the destination document.
See also: |
| destinationSelection |
| (NXSelection *)destinationSelection |
| Returns the destination selection, which describes how the linked data is represented in the destination document.
See also: |
| disposition |
| (NXDataLinkDisposition)disposition |
| Identifies the link as a source link, a destination link, or a broken link by returning one of the following values: |
| NX_LinkInDestination NX_LinkInSource NX_LinkBroken |
| See also: addLink:at: (NXDataLinkManager), dataLinkManager:startTrackingLink: (NXDataLinkManager delegate), break |
| initFromFile: |
| initFromFile:(const char *)filename |
| Initializes a newly allocated NXDataLink instance from filename, a link that was previously saved using the saveLinkIn: or writeToFile: method. The new link is generally used by adding it to a destination document's link manager with addLink:at:. Returns the link if it is successfully initialized; otherwise frees the link and returns nil.
See also: |
| initFromPasteboard: |
| initFromPasteboard:(Pasteboard *)pasteboard |
| Initializes a newly allocated NXDataLink instance from the pasteboard pasteboard. The new link is generally used by adding it to a destination document's link manager with addLink:at:.
In order for this method to succeed, a link must have been placed on the pasteboard using writeToPasteboard:, or the file name of a saved link (data of type NXFilenamePboardType with an extension of NXDataLinkFilenameExtension) must be on the pasteboard. Returns the link if it is successfully initialized; otherwise frees the link and returns nil. See also: |
| initLinkedToFile: |
| initLinkedToFile:(const char *)filename |
| Initializes a newly allocated NXDataLink instance corresponding to the entire file filename. The link is identified as a link to a file because it has no source selection. Returns the link if it is successfully initialized; otherwise frees the link and returns nil.
See also: |
| initLinkedToSourceSelection:managedBy:supportingTypes:count: |
| initLinkedToSourceSelection:(NXSelection *)selection |
| managedBy:linkManager supportingTypes:(const char *const *)newTypes count:(int)numTypes |
| Initializes a newly allocated NXDataLink instance corresponding to a selection in the source document described by selection. linkManager is the source document's link manager. newTypes is an array (with size numTypes) of pointers to the pasteboard types that linkManager's delegate is willing to provide (by copyToPasteboard:at: cheapCopyAllowed:) when a user of the link requests the data described by selection.
Typically, when the user uses the Copy command to copy linkable data, this method should be invoked to create a link corresponding to the data. The new link should be added to the pasteboard (by writeToPasteboard:) and immediately freed, since it will usually be of no further use to the source document. Many links so placed on the pasteboard will go unused and will simply be discarded when the pasteboard changes. If state identifying selection must be saved in the source document, the link manager's delegate should find out whether the selection is used by implementing dataLinkManager:startTrackingLink: (to discover if the selection gets used) and the Pasteboard owner's method pasteboardChangedOwner: (to discover when the pasteboard has changed, precluding the use of a link that was placed there). Returns the new link. See also: |
| lastUpdateTime |
| (time_t)lastUpdateTime |
| Returns the last time the link was updated. A link could be updated for many reasons; for example, a message could be sent to the source document's link manager telling it that its document was saved, or the link could be brought up to date with an updateDestination message.
See also: |
| linkNumber |
| (NXDataLinkNumber)linkNumber |
| Returns a destination link's link-number, which may be useful in identifying the link. This number is constant through the life of the document, and unique among the document's links; it is not meaningful in source links. |
| manager |
| (NXDataLinkManager *)manager |
| Returns the link's link manager, or nil if it doesn't have one. (For example, returns nil if the link is broken.) |
| openSource |
| openSource |
| Opens the document corresponding to the link's source selection. This message only has meaning when sent to a destination link. Returns self if the source document is successfully opened, nil otherwise.
See also: |
| saveLinkIn: |
| saveLinkIn:(const char *)directoryName |
| Saves the link with a file name provided by the user. This method should be invoked through the Publish Selection command. It runs the SavePanel to prompt the user for a filename to save the link to. The SavePanel's initial directory is provided in directoryName. It then writes the link using the writeToFile: method. Returns self if the link is successfully saved; nil otherwise.
See also: |
| setUpdateMode: |
| setUpdateMode:(NXDataLinkUpdateMode)mode |
| Sets the link's update mode to mode, which must be one of the following values: |
| NX_UpdateContinuously NX_UpdateWhenSourceSaved NX_UpdateManually NX_UpdateNever |
| A mode of NX_UpdateContinuously updates the link's destination data every time a sourceEdited message is sent to the source link. A mode of NX_UpdateWhenSourceSaved updates the link's destination data every time a documentSaved (or related) message is sent to the source link's link manager. A mode of NX_UpdateManually updates the link's destination data every time a updateDestination message is sent to the destination link; this message can be sent programmatically or by the data link panel. A mode of NX_UpdateNever makes the link never update; once a destination link has been set to this mode, it can't be set back to any other mode until it is broken. (This mode is used for link buttons, for example.)
This message only has meaning when sent to a destination link or a broken link. Returns self. See also: |
| sourceAppName |
| (const char *)sourceAppName |
| Returns the name (as returned by Application's appName method) of the application containing the source link.
See also: |
| sourceEdited |
| sourceEdited |
| Sent to a source link to inform it that the data referred to by its source selection has changed. If the link's destination link has been set to update continuously, the destination will be updated.
This message only has meaning if sent to a source link. An application will only know of the source links that are being used in its document if the data link manager's delegate tracks links individually and responds to dataLinkManager:startTrackingLink: messages. However, an application doesn't need to track source links individually unless it wishes to allow continuous updating. Returns self unless the link's destination is set to continuously update and the update fails; in this case, the method returns nil. See also: |
| sourceFilename |
| (const char *)sourceFilename |
| Returns the file name of the source document, as set by any of several NXDataLinkManager methods for the source document.
See also: |
| sourceSelection |
| (NXSelection *)sourceSelection |
| Returns the source selection, or nil if the link refers to an entire file (in which case the source file can be retrieved from sourceFilename).
See also: |
| types |
| (const NXAtom *)types |
| Returns the pasteboard types that the source document can provide when the data for the link's source selection is required.
See also: |
| updateDestination |
| updateDestination |
| Updates the data referred to by the link's destination selection. This message can be sent to a source link or a destination link. If it's sent to a destination link, it will usually open the source document if it isn't already open. If it is sent to a source link, it will usually force the destination data to be immediately updated (which is generally less desirable than sending the source link a sourceEdited message, since that would allow the update to occur at the normal time). If the destination must be updated, it will be done by sending a pasteFromPasteboard:at: or importFile:at: message to the destination link manager's delegate.
See also: |
| updateMode |
| (NXDataLinkUpdateMode)updateMode |
| Returns the link's update mode, which determines when the data referred to by the link's destination selection will be updated. Possible return values are: |
| NX_UpdateContinuously NX_UpdateWhenSourceSaved NX_UpdateManually NX_UpdateNever |
| A description of these values can be found in the method description for setUpdateMode:. |
| writeToFile: |
| writeToFile:(const char *)filename |
| Writes the link into the file filename. This allows selections to be published by the file system; the link can be read in later using initFromFile:. Returns self if the link is successfully written, nil otherwise.
See also: |
| writeToPasteboard: |
| writeToPasteboard:(Pasteboard *)pasteboard |
| Writes the link onto the pasteboard pasteboard, allowing other applications to paste both copied data and the link referring to that data. When a link is written to a pasteboard, the type NXDataLinkPboardType must be included in the pasteboard's types, either using declareTypes:num:owner: or addTypes:num:owner:. The link can be read in later using initFromPasteboard:. Returns self if the link is successfully written, nil otherwise.
See also: |