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:
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: | ||||||||||||||||||||||||||
Overridden Methods | The following method is inherited and available for use by your subclass of this class.
|
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
Returns
| 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.
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
Returns
| 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.
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
This method returns a reference to the content storage unit for this drag-and-drop object.
Signature
ODStorageUnit *GetContentStorageUnit () |
Parameters
None.
Returns
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
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
Returns
| 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.
This method returns additional information about the current drag-and-drop operation.
Signature
ODULong GetDragAttributes () |
Parameters
None.
Returns
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.
Exception Handling
kODErrNoDragManager | No platform-specific drag system service is available. |
This method returns drag reference number associated with the current drag operation.
Signature
ODPlatformDragReference GetDragReference () |
Parameters
None.
Returns
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. |
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
| kODTrue | Links can be created. |
| kODFalse | Links cannot be created. |
| 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. |
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. |
Returns
| 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
This method initiates a drag operation.
Signature
ODDropResult StartDrag (ODFrame *srcFrame,
ODType imageType,
ODByteArray *image,
ODPart **destPart,
ODByteArray *refCon)
|
Parameters
Returns
| 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