Programming Reference: ODDragAndDrop

# Programming Reference

## ODDragAndDrop

Class Definition File | DragDrp.idl
Class C++ Binding | DragDrp.xh

Class Hierarchy

    SOMObject
       ODObject
          ODDragAndDrop

Description

An object of the ODDragAndDrop class provides the mechanism for dragging and dropping objects within a part, between parts, between documents, and between an OpenDoc document and a non-OpenDoc application.

The drag-and-drop facility of OpenDoc depends on system services provided by the platform. They include a service to allow data to be transferred within a process, or between processes and a system-wide mouse tracking service that can notify a process about the location and state of the mouse during a drag operation.

When a document is opened, the session object creates a single drag-and-drop object. All parts of that document share the drag-and-drop object; you can obtain a reference to it by calling the session object's GetDragAndDrop method. You must not cache this object; instead, you must call the session object's GetDragAndDrop method when you need the drag-and-drop object.

Data transfers requested by any part operate on the drag-and-drop object's content storage unit. You can obtain a reference to that storage unit by calling the drag-and-drop object's GetContentStorageUnit method. You must not cache that storage unit; instead, you must call the GetContentStorageUnit method when you need to access the storage unit.

A drag initiated by an OpenDoc part moves or copies a single item, called a drag item. Some items that can be dragged are a content item, a text selection, and a selected embedded frame. A drag initiated by a non-OpenDoc application may have more than one drag item. For example, a drag initiated by an application that manipulates the file system might include several files.

When your part receives a mouse-down event that occurred within an item that can be dragged, you can initiate a drag. Initiating a drag involves acquiring the drag-and-drop object from the session object, clearing the drag-and-drop object's content storage unit, copying data from the item to be dragged into the content storage unit, and starting a drag action. Once the drag is initiated, the drag-and-drop object notifies a facet when the mouse passes over it. If the mouse button is released over a facet, the facet calls its part's Drop method to notify the part of the drop. The destination part can retrieve the dragged data, using the supplied drag-item iterator. A drag-item iterator is an object of the ODDragItemIterator class; it allows the part to iterate through the drag items and obtain a reference to the content storage unit for each one.

For more information on drag-and-drop operations, see the chapter on data transfer in the OpenDoc Programming Guide. For more information on using a link specification to indicate that the source part can create a link, see the class description for "ODLinkSource".

OS/2 Implementation Considerations

Data transfer for standard OS/2 drag-and-drop rendering mechanisms and formats (RMF) is achieved using the standard OS/2 kinds as value types of the kODPropContents property in the drag-and-drop object storage unit. The following is a list of the supported standard OS/2 RMFs and their associated kinds:

RMF | Standard Kind
<DRM_OS2FILE,DRF_BITMAP> | kODKindOS2Bitmap
<DRM_OS2FILE,DRF_DIB> | kODKindOS2DIB
<DRM_OS2FILE,DRF_DIF> | kODKindOS2DIF
<DRM_OS2FILE,DRF_DSPBITMAP> | kODKindOS2DspBitmap
<DRM_OS2FILE,DRF_METAFILE> | kODKindOS2Metafile
<DRM_OS2FILE,DRF_OEMTEXT> | kODKindOS2OEMText
<DRM_OS2FILE,DRF_OWNERDISPLAY> | kODKindOS2OwnerDisplay
<DRM_OS2FILE,DRF_PTRPICT> | kODKindOS2PtrPict
<DRM_OS2FILE,DRF_RTF> | kODKindOS2RTF
<DRM_OS2FILE,DRF_SYLK> | kODKindOS2SYLK
<DRM_OS2FILE,DRF_TEXT> | kODKindOS2Text
<DRM_OS2FILE,DRF_TIFF> | kODKindOS2TIFF

Parts that support any of the above standard OS/2 RMFs should register the corresponding standard kind. Parts that support any other standard or private OS/2 rendering mechanisms and formats should register the corresponding RMF pairs as kinds. This ensures that if non-OpenDoc content of a certain type is dropped into a container part, the appropriate part editor is chosen to handle the operation.

Methods

The methods defined by the ODDragAndDrop class include:

- CanEmbed (OS/2)
- CanIncorporate (OS/2)
- Clear
- GetContentStorageUnit
- GetDataFromDragManager (OS/2)
- GetDragAttributes (OS/2, Windows)
- GetDragReference
- ShowPasteAsDialog (OS/2, Windows)
- StartDrag

Overridden Methods

The following method is inherited and available for use by your subclass of this class.

somUninit | The somUninit method disposes of the storage created for a SOM object. If you subclass this class, you can override this method. Your override method does not need to call its inherited method. Your override method must dispose of any storage created for this object, including any storage related to additional instances variables initialized.

### CanEmbed (OS/2)

This method queries the registration manager for a part editor capable of handling the content of the specified drag-and-drop content storage unit.

Signature

    ODBoolean CanEmbed (ODStorageUnit *dropSU)

Parameters

dropSU (ODStorageUnit *) - input

  A reference to the content storage unit for the drag item.

Returns

rv (ODBoolean) - returns

  A flag indicating whether a part editor was found.

  kODTrue | A part editor was found.
  kODFalse | A part editor was not found.

Remarks

A container part should call this method in its DragEnter method to determine whether it can accept the drop.

### CanIncorporate (OS/2)

This method indicates whether the type of data in the specified drag-and-drop content storage unit matches the specified kind.

Signature

    ODBoolean CanIncorporate (ODStorageUnit *dropSU,
                              ODType kind)

Parameters

dropSU (ODStorageUnit *) - input

  A reference to the content storage unit for the drag item.

kind (ODType) - input

  An OpenDoc part kind, a standard OS/2 kind, or a private OS/2 drag-and-drop RMF pair.

Returns

rv (ODBoolean) - returns

  A flag indicating whether a match was found.

  kODTrue | A match was found.
  kODFalse | A match was not found.

Remarks

A non-container part should call this method in its DragEnter method for the kinds that it supports to determine whether it can accept the drop.

### Clear

This method clears the content storage unit for this drag-and-drop object.

Signature

    void Clear ()

Parameters

None.

Returns

None.

Remarks

When your part initiates a drag, you must call this method immediately before calling the GetContentStorageUnit method. Doing so ensures that the content storage unit is empty and ready for drag-and-drop data transfer.

Exception Handling

kODErrNoDragManager | No platform-specific drag system service is available.

Related Methods

- ODDragAndDrop::GetContentStorageUnit

### GetContentStorageUnit

This method returns a reference to the content storage unit for this drag-and-drop object.

Signature

    ODStorageUnit *GetContentStorageUnit ()

Parameters

None.

Returns

rv (ODStorageUnit *) - returns

  A reference to the content storage unit.

Remarks

When your part initiates a drag, you should first call the Clear method, then call this method and copy data from the drag item into the returned storage unit. The drag-and-drop object handles the creation and destruction of its content storage unit, so you cannot dispose of or release the returned storage unit.

You must not cache the returned storage unit; instead, you must call this method when you need to access the content storage unit.

Exception Handling

kODErrNoDragManager | No platform-specific drag system service is available.

Related Methods

- ODDragAndDrop::Clear

### GetDataFromDragManager (OS/2)

This method carries on the rendering conversation with the source of the drop to obtain the data and places the rendered data in the returned storage unit, if successful.

Signature

    ODBoolean GetDataFromDragManager (ODStorageUnitView *theSUView,
                                      ODStorageUnit **renderedSU)

Parameters

theSUView (ODStorageUnitView *) - input

  The storage unit view created by focusing the drag-item storage unit on the kODDragitem value of the kODPropContents property.

renderedSU (ODStorageUnit **) - output

  A pointer to the address of the storage unit containing the rendered data. The actual storage unit is created by the drag-and-drop object.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the rending was successful.

  kODTrue | The data was successfully rendered.
  kODFalse | The data could not be rendered.

Remarks

This method should be called by parts in their Drop method for every drag-item storage unit referenced by the drag-item iterator. Prior to calling the method, the drag-item storage unit must be focused on kODDragitem value of kODPropContents property, and a storage-unit view must be created. Then, the GetDataFromDragManager method is called passing in the storage-unit view and a pointer for the rendered storage unit. The part must not free the returned storage unit.

### GetDragAttributes (OS/2, Windows)

This method returns additional information about the current drag-and-drop operation.

Signature

    ODULong GetDragAttributes ()

Parameters

None.

Returns

rv (ODULong) - returns

  A flag specifying the drag attributes of the current drag-and-drop operation or 0 if no drag operation is in progress.

  This parameter can return any of the following flags. Some flags are relevant to a part tracking a drag event that has entered one of its facets; others are relevant to the part that is the destination of a drop. These values can be tested for the presence of a particular flag using the bitwise AND operator (for example, the & operator in C++).

  kODDragIsInSourceFrame | The drag has not left the source frame.
  kODDragIsInSourcePart | The drag has not left the source part.
  kODDropIsInSourceFrame | The drop is occurring in the source frame of the drag.
  kODDropIsInSourcePart | The drop is occurring in the same part as the source frame of the drag.
  kODDropIsMove | The drag items are being moved.
  kODDropIsCopy | The drag items are being copied.
  kODDropIsLink | The destination part should display the Paste As dialog box.
  kODDropIsPasteAs | The destination part should display the Paste As dialog box.

Remarks

If a drag enters your part, or a drop occurs in your part, you can call this method to determine how your part should respond.

- If your part is tracking a drag that has entered one of its facets, you can decide whether to provide the user visual feedback by checking whether the kODDragIsInSourceFrame or kODDragIsInSourcePart flags are set in the returned value.

- If a drop occurred in your part, you can determine the appropriate response by checking which of the drop flags are set in the returned value.

Exception Handling

kODErrNoDragManager | No platform-specific drag system service is available.

### GetDragReference

This method returns drag reference number associated with the current drag operation.

Signature

    ODPlatformDragReference GetDragReference ()

Parameters

None.

Returns

rv (ODPlatformDragReference) - returns

  A platform-specific drag reference number of the current drag operation or kODNULL if no drag operation is active.

Remarks

You should call this method to obtain the reference number to be used in direct calls to the drag manager, for example, to perform drag highlighting.

Exception Handling

kODErrNoDragManager | No platform-specific drag system service is available.

### ShowPasteAsDialog (OS/2, Windows)

This method displays the Paste As dialog box and sets the appropriate dialog items according to the input parameters.

Signature

    ODBoolean ShowPasteAsDialog (ODBoolean canPasteLink,
                                 ODPasteAsMergeSetting mergeSetting,
                                 ODFacet *facet,
                                 ODTypeToken viewType,
                                 ODStorageUnit *contentSU,
                                 ODPasteAsResult *theResult)

Parameters

canPasteLink (ODBoolean) - input

  A flag indicating whether the destination part allows a link to be created. This parameter can be set to one of the following values:

  kODTrue | Links can be created.
  kODFalse | Links cannot be created.

mergeSetting (ODPasteAsMergeSetting) - input

  A flag indicating whether embedding and merging are supported. This value determines which radio button in the At the Destination group box is initially selected and whether the other button is available.

  kODPasteAsEmbed | Embed As is initially selected; Merge with Contents is available.
  kODPasteAsEmbedOnly | Embed As is selected; Merge with Contents is disabled.
  kODPasteAsMerge | Merge with Contents is initially selected; Embed As is available.
  kODPasteAsMergeOnly | Merge with Contents is selected; Embed As is disabled.

facet (ODFacet *) - input

  A reference to the facet in which the drop is to occur.

viewType (ODTypeToken) - input

  A tokenized string representing the initial setting for the view type of the embedded part (if embedding is chosen).

  This parameter must be the tokenized form of one of the following view-type constants. You can call the session's Tokenize method to obtain a token corresponding to one of these constants.

  kODViewAsFrame | Framed view type.
  kODViewAsLargeIcon | Large-icon (standard) view type
  kODViewAsSmallIcon | Small-icon view type.
  kODViewAsThumbNail | Thumbnail view type.

contentSU (ODStorageUnit *) - input

  A reference to the content storage unit for the drag item to be pasted.

theResult (ODPasteAsResult *) - output

  A structure reflecting the user's selection in the Paste As dialog box.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the user clicked the Paste button to leave the Paste As dialog box.

  kODTrue | The user clicked the Paste button.
  kODFalse | The user canceled out of the dialog box.

Remarks

If your part is the destination of a drop and the user presses the appropriate key(s), you can call this method to display the Paste As dialog box for a particular drag item. When your part is the destination of a drop, you should call the GetDragAttributes method of the drag-and-drop object; if the kODDropIsPasteAs flag is set in the drag attributes, you must call this method.

If the canPasteLink parameter is kODTrue, the content storage unit contains a link specification and the draft permissions allow writing, then the Paste with Link check box is enabled and its initial setting is checked.

If the user clicks the Paste button, this method returns kODTrue and sets the fields of the theResult output parameter to indicate the selections the user made in the Paste As dialog box; in this case, you must deallocate the non-null selectedKind, translateKind, and editor fields of the ODPasteAsResult structure when you are finished using them.

If the user cancels the dialog box, this method returns kODFalse and you do not need to take any further action.

Exception Handling

kODErrIllegalNullStorageUnitInput | The contentSU parameter is null.
kODErrNullFacetInput | The facet parameter is null.
kODErrNullPasteAsResultInput | The theResult parameter is null.

Related Methods

- ODDragAndDrop::GetDragAttributes (OS/2, Windows)
- ODSession::Tokenize

### StartDrag

This method initiates a drag operation.

Signature

    ODDropResult StartDrag (ODFrame *srcFrame,
                            ODType imageType,
                            ODByteArray *image,
                            ODPart **destPart,
                            ODByteArray *refCon)

Parameters

srcFrame (ODFrame *) - input

  A reference to the frame in which the drag is initiated.

imageType (ODType) - input

  A platform-specific drag-image type, indicating the type of image OpenDoc should display to the user as dragging feedback.

image (ODByteArray *) - input

  A byte array whose buffer contains the data of the image to be dragged.

destPart (ODPart **) - output

  A reference to the destination part. The content of this parameter is undefined if the drop is unsuccessful.

refCon (ODByteArray *) - input

  A byte array whose buffer contains extra platform-specific information needed for dragging.

Returns

rv (ODDropResult) - returns

  A flag indicating the result of the drag-and-drop operation. This parameter can return any of the following values:

  kODDropCopy | A successful copy operation occurred
  kODDropFail | The drop operation was unsuccessful.
  kODDropMove | A successful move operation occurred.
  kODDropUnfinished | An asynchronous drop was started.

Remarks

If your part initiates a drag, you should call this method after copying data from the drag item into the content storage unit for this drag-and-drop object. If the drag item includes any frames, you should call the SetDragging method for each frame to prevent it from being dragged into itself.

The content of the image parameter's buffer depends on the drag-image type.

During the drag operation, the platform-specific drag manager displays the image specified in the image parameter and moves the image as the user moves the mouse pointer. After the user drops the image by releasing the mouse button, this method returns the result of the operation.

On platforms that support asynchronous drag-and-drop operations, this method always returns kODDropUnfinished.

Exception Handling

kODErrNoDragManager | No platform-specific drag system service is available.

Related Methods

- ODFrame::SetDragging
- ODPart::Drop

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]