Programming Reference: ODDragItemIterator

# Programming Reference

## ODDragItemIterator

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:

- First
- IsNotComplete
- Next

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.

### First

This method begins the iteration and returns a reference to the first storage unit in the iteration sequence.

Signature

    ODStorageUnit *First ()

Parameters

None.

Returns

rv (ODStorageUnit *) - returns

  A reference to the first storage unit in the iteration sequence.

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.

### IsNotComplete

This method indicates whether the iteration is incomplete.

Signature

    ODBoolean IsNotComplete ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the iteration is incomplete.

  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.

### Next

This method returns a reference to the next storage unit in the iteration sequence.

Signature

    ODStorageUnit *Next ()

Parameters

None.

Returns

rv (ODStorageUnit *) - returns

  A reference to the next storage unit in the iteration sequence or kODNULL if you have reached the last storage unit.

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.

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