Class Definition File | DgItmIt.idl | ||
Class C++ Binding | DgItmIt.xh | ||
Class Hierarchy |
SOMObject ODObject ODDragItemIterator | ||
Description | An object of the ODDragItemIterator class provides access to the content storage units for all the drag items of a drag-and-drop object. Each drag item is an item being copied or moved in a drag-and-drop operation. Its content storage unit contains the data being transferred. Once a drag operation is initiated (by calling its drag-and-drop object's StartDrag method), the drag-and-drop object notifies a part when the mouse pointer passes over one of its facets. In addition to providing the mouse location, the drag-and-drop object also supplies the part with a drag-item iterator. Similarly, if the mouse pointer is released over a frame, the part is notified of the mouse location and supplied with a drag-item iterator. In both cases, the part might use the drag-item iterator to examine each drag item from the incoming drag operation and decide whether to provide destination feedback and whether to accept the drop event. While you are using a drag-item iterator, you should not modify the list of drag items. You must postpone adding items to or removing items from the list of drag items until after you have deleted the iterator. For more information related to drag-and-drop objects, see the description for the class ODDragAndDrop. For more information on drag-and-drop operations, see the chapters on data transfer and OpenDoc runtime features in the OpenDoc Programming Guide. For more information on accessing objects through iterators, see the chapters on OpenDoc runtime features in the OpenDoc Programming Guide. | ||
Methods | The methods defined by the ODDragItemIterator class include: | ||
Overridden Methods | The following method is inherited and available for use by your subclass of this class.
|
This method begins the iteration and returns a reference to the first storage unit in the iteration sequence.
Signature
ODStorageUnit *First () |
Parameters
None.
Returns
Remarks
Your part must call this method before calling this drag-item iterator's IsNotComplete method for the first time. This method may be called multiple times; each time, it resets the iteration.
Because storage units are valid only during the iteration, you should not cache a reference to the returned storage unit. This method does not increment the reference count of the returned storage unit.
Exception Handling
kODErrIteratorOutOfSync | The list of drag items was modified while the iteration was in progress. |
This method indicates whether the iteration is incomplete.
Signature
ODBoolean IsNotComplete () |
Parameters
None.
Returns
kODTrue | The iteration is incomplete. |
kODFalse | The iteration is complete. |
Remarks
Your part calls this method to test whether more storage units remain in the iteration sequence. This method returns kODTrue if the preceding call to the First or Next method found a storage unit. This method returns kODFalse when you have examined all the storage units (that is, when the previous call to First or Next returned kODNULL).
Exception Handling
kODErrIteratorNotInitialized | This method was called before calling the First or Next method to begin the iteration. |
kODErrIteratorOutOfSync | The list of drag items was modified while the iteration was in progress. |
This method returns a reference to the next storage unit in the iteration sequence.
Signature
ODStorageUnit *Next () |
Parameters
None.
Returns
Remarks
If your part calls this method before calling this drag-item iterator's First method to begin the iteration, this method works the same as calling the First method.
Because storage units are valid only during the iteration, you should not cache a reference to the returned storage unit. This method does not increment the reference count of the returned storage unit.
Exception Handling
kODErrIteratorOutOfSync | The list of storage units was modified while the iteration was in progress. |