Programming Guide

Writing to a Data-Transfer Object

You write data to a data-transfer object when the user cuts, copies, or drags data from your part or when you create or update the source of a link. This section discusses how to place that data into the data-transfer object.

This section does not discuss how your part handles cutting (or moving) differently from copying. Cutting involves removing data from your part, including possibly one or more frames of embedded parts. Removing an embedded part is discussed in "Removing an Embedded Part"; other issues related to cutting operations are discussed in "Handling Cut Data".

Writing Intrinsic Content

Intrinsic content plus possibly one or more embedded parts is the most general configuration of data that you put into a data-transfer object. If the data to be written consists of a combination of your part's intrinsic content plus embedded parts, you need to write your own intrinsic content, and you need to clone the embedded frames as well. If the data includes link sources or destinations, you need to clone those objects also. These are the basic steps to take, regardless of whether or not your intrinsic content is accompanied by embedded frames and other objects:

1. Gain access to the data-transfer object and prepare to write to it. (See, for example, the initial steps under "Copying or Cutting to the Clipboard", "Initiating a Drag", "Creating a Link at the Source", and "Updating a Link at the Source".)

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. Add a property of kODPropContents to the data-transfer object's content storage unit. You should write all the data to be transferred into this property.

4. Write your data into the data-transfer object's content storage unit using the storage unit's SetValue or SetPromiseValue. The preferred presentation of your data should be written first.

5. Write a suggested frame shape using the kODPropSuggestedFrameShape property.

6. If appropriate, write a link specification into the data-transfer object, as described in "Link Specification".

7. Perform any closing tasks specific to the individual kind of data-transfer object you are writing to. (See, for example, the final steps under "Copying or Cutting to the Clipboard", "Initiating a Drag", "Creating a Link at the Source", and "Updating a Link at the Source".)

If this operation is a cut rather than a copy, note the additional considerations listed in "Handling Cut Data".

Writing a Single Embedded Frame

If the data to be written consists of a single embedded frame you need to clone the embedded part and frame to the data-transfer object's storage unit. These are the basic steps to take:

1. Gain access to the data-transfer object and prepare to write to it. (See, for example, the initial steps under "Copying or Cutting to the Clipboard", "Initiating a Drag", "Creating a Link at the Source", and "Updating a Link at the Source".)

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 embedded part into the data-transfer object by calling your draft's Clone method. Unlike writing intrinsic content, you do not add a kODPropContents property (the embedded part itself does that), a kODPropName property (OpenDoc does that), or a kODPropSuggestedFrame property (you instead add a kODPropContentFrame property).

   Be sure to perform the cloning operation in this order:

   1. Add a property of type kODPropContentFrame to the data-transfer object's content storage unit. The presence of this property tells a destination part that the data being transferred is a frame without surrounding intrinsic content, and also signals to the embedded part (the part being cloned) that it can write a promise instead of its actual content.

      It is important not to clone the frame yet. Wait until step 3c, or else the embedded part itself will be cloned into the wrong storage unit.

   2. Clone the embedded part into the data-transfer object's content storage unit.

   3. Clone the embedded part's frame into the data-transfer object's draft (into any storage unit other than the content storage unit). This cloning operation must occur after the embedded part is cloned.

   4. Add a value of type kODWeakStorageUnitRef to the kODPropContentFrame property of the data-transfer object's content storage unit. Create a weak persistent reference from that value to the cloned frame. This allows a destination part, upon recognizing the kODPropContentFrame property, to locate the frame for the part in the data-transfer object.

4. Optionally, write any intrinsic data you want associated with the frame (such as a drop shadow or other visual adornment) as proxy content. Add a property (of type kODPropProxyContents) to the data-transfer object, and write your data into it as a value that you recognize. If the transferred part is subsequently pasted into a part that also recognizes that value and knows how to interpret it, the added frame characteristics can be duplicated.

5. If the embedded part is the entire source or destination of a link, you need to write additional proxy content, as described in "Writing Linked Content to Storage". Follow the instructions in the note "Writing Links for Data Transfer".

6. If appropriate, write a link specification into the data-transfer object, as described in "Link Specification".

7. Perform any closing tasks specific to the individual kind of data-transfer object you are writing to. (See, for example, the final steps under "Copying or Cutting to the Clipboard", "Initiating a Drag", "Creating a Link at the Source", and "Updating a Link at the Source".)

If this operation is a cut rather than a copy, note the additional considerations listed in "Handling Cut Data".