Programming Guide

Reading from a Data-Transfer Object

You read from a data-transfer object when the user pastes or drops data into your part or when you create or update the destination of a link. This section discusses how to extract that data from the data-transfer object.

When placing transferred data into your part, what you do with the data depends on how the part kinds within the transferred data relate to the part kind of your part (the destination part).

Incorporating Intrinsic Content

As the destination of a data transfer, your part incorporates the intrinsic content of the data-transfer object into your own part's intrinsic content (and embeds whatever embedded parts the transferred content contains) if all of these conditions apply:

• The intrinsic content of the transferred data is stored in at least one part kind that you can incorporate into your part.

• The user has not specified Embed As in the Paste As dialog box.

• The data-transfer object's content storage unit does not contain a property named kODPropContentFrame. (If it does, the transferred data consists of a single embedded frame without surrounding intrinsic content, and the data should be embedded; see "Frame Shape or Frame Annotation".)

When incorporating transferred data, you should read the highest-fidelity part kind. The highest-fidelity part kind is the first value, in storage order, that your part editor understands.   If the transferred data includes a kODPropPreferredKind property, however, it takes precedence over fidelity; you should attempt to read it first.    

Incorporating involves reading intrinsic content plus possibly cloning embedded frames, links, and other objects. Figure 64 summarizes the steps involved.

Figure 64. Incorporating the Content of a Data-Transfer Object

View figure.

Here, in more detail, are the basic steps to take when incorporating:

1. Gain access to the data-transfer object and prepare to read from it. (See, for example, the initial steps under "Pasting from the Clipboard", "Dropping", "Creating a Link at the Destination", and "Updating a Link at the Destination".)

2. Start the cloning operation, as described under "Cloning". Specify the appropriate kind of cloning operation, using one of the constants listed in Table 9.

3. In the kODPropContents property of the data-transfer object's content storage unit, focus on the value that corresponds to the highest-fidelity part kind that you can incorporate into your part. (It may not be the highest-fidelity value present in the property.) Read the data into your part, following your own content model.

   As you encounter persistent references to objects, clone each object into your draft by calling the Clone method of the data-transfer object's draft These persistent referenced objects can be embedded frames, link-source objects, link objects, auxiliary storage units, and so on. Retain the cloned objects IDs for instantiation after cloning is complete, rather than reconstructing the objects. Adjust your persistent references to point to the newly cloned objects. See "Clone" under "Cloning Sequence" for additional information.

4. End the cloning operation, as described in "EndClone" in "Cloning Sequence".

5. If you are incorporating the result of a drop, there can be a kODPropMouseDownOffset property in the data-transfer object's content storage unit. If so, focus on that property, read its value, and, if appropriate for your content model, use the value to position the incorporated data to the drop location.

   If you are incorporating translated data, you must read this property from the original data-transfer object, not the cloned storage unit.

6. If the cloning is successful, instantiate each cloned embedded frame into memory using your draft's AcquireFrame method and call the frame's SetContainingFrame method to make your part's display frame the containing frame of the new embedded frame.        

   Create additional embedded frames as necessary, if your part's content model specifies that the new part is to appear in more than one of your display frames. If you do create new frames, synchronize them with the first (source) frame; see "Synchronizing Display Frames" for more information.

7. Change each new frame's link status to reflect its current location. If your part does not support linking, you must nevertheless change your cloned embedded frames' link status (to kODNotInLink).

8. If any of the objects that you have cloned into your part is a link-source object or link object, follow the procedures described in "Reading Linked Content from Storage" to make sure that the objects are valid.

9. If any newly embedded frame is visible, assign a facet or facets to it, as described in "Adding a Facet".

10. Perform any closing tasks specific to the individual kind of data-transfer object you are reading from. (See, for example, the final steps under "Pasting from the Clipboard", "Dropping", "Creating a Link at the Destination", and "Updating a Link at the Destination".) (If you are incorporating translated data, you can at this time remove the cloned temporary storage unit from your draft.)

Embedding a Single Part

As the destination of a data transfer, your part embeds the entire contents of the data-transfer object as a single part (plus whatever embedded parts it contains) if any of these conditions apply:

• The intrinsic content is of a part kind that you cannot incorporate.

• The user has specified Embed As in the Paste As dialog box.

• The transferred data consists of a single embedded frame, without surrounding intrinsic content (regardless of its part kind). In this case the data-transfer object's content storage unit contains a property named kODPropContentFrame, that is a signal that the data consists of a single frame and should be embedded, even if it is of a part kind that you can incorporate. See "Frame Shape or Frame Annotation".

Embedding data from a data-transfer object as a single part involves, basically, cloning the content storage unit into your draft and then providing for a frame and facets for the new part. The steps involved are summarized in Figure 65.

Figure 65. Embedding the Content of a Data-Transfer Object

View figure.

Here, in more detail, are the basic steps to take when embedding:

1. Gain access to the data-transfer object and prepare to read from it. (See, for example, the initial steps under "Pasting from the Clipboard", "Dropping", "Creating a Link at the Destination", and "Updating a Link at the Destination".)

   If you are embedding translated data, you already will have cloned the data into a new storage unit in your draft, and you already will have translated it. Skip to step 6.

2. Start the cloning operation, as described under "Cloning". Specify the appropriate kind of cloning operation, using one of the constants listed in Table 9.

3. Clone the data-transfer object's content storage unit into a new storage unit in your draft, using the Clone method of the data-transfer object's draft.

4. If there is a property named kODPropContentFrame in the original storage unit, read the storage-unit reference it contains and use that reference to clone the new part's frame into your draft. (Cloning the data-transfer object's content storage unit alone does not copy the frame, because the reference is a weak persistent reference.)

5. End the cloning operation. If any of the following conditions apply, notify the embedded part's future part editor that it should use a specific part kind when reading the part:

   • If the data has been translated.

   • If this embedding has occurred as a result of a user selection in the Paste As dialog box and the user has chosen a part kind that is not the preferred kind.

   • If a preferred kind property does not exist and the user has chosen a part kind that is not the highest-fidelity (first) value stored in the transferred storage unit's contents property.  

   In any of these cases, create a property with the name kODPropPreferredKind in the cloned storage unit (if the property does not already exist) and write into it a value that specifies the part kind the editor should use.

6. If this embedding has occurred as a result of a user selection in the Paste As dialog box and the user has chosen a specific part editor to edit the part, add a property with the name kODPropPreferredEditor to the cloned storage unit, and write into it the editor ID (returned in the editor field of the ODPasteAsResult structure) of the preferred editor.

7. If the original storage unit contains a property named kODPropProxyContent, that property contains any proxy content that the part's original containing part wanted associated with the frame, such as a drop shadow or other visual adornment. (This property is absent if the transferred data includes any intrinsic content in addition to the embedded frame.)

   Focus the cloned storage unit on the kODPropProxyContent property and read in the information from the data-transfer object (not from the cloned storage unit). You must understand the format of the proxy content in order to use it; it is subsumed in your own part's intrinsic content to be associated with the frame. If you do not understand the format, ignore the data.

8. If you are embedding the result of a drop, there may be a property named kODPropMouseDownOffset in the content storage unit of the data-transfer object, not the cloned storage unit. If so, focus on that property, read its value, and, if appropriate for your content model, use the value to position the embedded data in relation to the drop location.

9. Recreate the new part's frame, if it was provided in the kODPropContentFrame property, using your draft's AcquireFrame method and call its SetContainingFrame method to assign your part's display frame as the containing frame.     If no frame was provided, you must create one. To create a frame:

   • Obtain the suggested frame shape, if it exists, from the data-transfer object not the cloned storage unit. It should be in a kODPropSuggestedFrameShape property. If it is not there, use a default frame shape.

   • Recreate the new part; pass the cloned storage unit's ID to your draft's AcquirePart method.

   • Create the frame for the part, using your draft's CreateFrame method.

10. Change the link status of the new frame to reflect its current location. If your part does not support linking, you must change your new embedded frame's link status to kODNotInLink.

11. If the newly embedded frame is visible, assign facets to it, as described in "Adding a Facet".

12. Perform any closing tasks specific to the individual kind of data-transfer object you are reading from. (See, for example, the final steps under "Pasting from the Clipboard", "Dropping", "Creating a Link at the Destination", and "Updating a Link at the Destination".)