
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 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:
-
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 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:
-
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 ]