
Programming Guide
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).
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 65 summarizes the steps involved.
Figure 65. Incorporating the Content of a Data-Transfer Object
View figure.
Here, in more detail, are the basic steps to take when incorporating:
- 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".)
- Start the cloning operation, as described under "Cloning". Specify the appropriate kind of cloning operation, using one of the
constants listed in Table 9.
- 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.
- End the cloning operation, as described in "EndClone" in "Cloning Sequence".
- 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.
- 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.
- 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).
- 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.
- If any newly embedded frame is visible, assign a facet or facets to it, as
described in "Adding a Facet".
- 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.)
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 66.
Figure 66. Embedding the Content of a Data-Transfer Object
View figure.
Here, in more detail, are the basic steps to take when embedding:
- 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.
- Start the cloning operation, as described under "Cloning". Specify the appropriate kind of cloning operation, using one of the
constants listed in Table 9.
- 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.
- 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.)
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- If the newly embedded frame is visible, assign facets to it, as described
in "Adding a Facet".
- 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".)
[ Top | Previous | Next | Contents | Index | Documentation Homepage ]