ClipboardCopyWithRectangle Method

  • Article

ClipboardCopyWithRectangle Method

Copies the IInkStrokeDisp objects that are contained within the known rectangle to the Clipboard.

Declaration

[C++]

HRESULT ClipboardCopyWithRectangle (
    [in] IInkRectangle* rectangle,
    [in, optional, defaultvalue(ICF_Default)] InkClipboardFormats formats,
    [in, optional, defaultvalue(ICB_Default)] InkClipboardModes modes,
    [out, retval] IDataObject** DataObject
);

[Microsoft® Visual Basic® 6.0]

Public Function ClipboardCopyWithRectangle( _
    rectangle As InkRectangle, _
    [formats As InkClipboardFormats = ICF_CopyMask], _
    [modes As InkClipboardModes = ICB_Copy] _
) As IDataObject

Parameters

rectangle

[in] Specifies the rectangle that contains the strokes to copy to the Clipboard.

formats

[in, optional] Specifies the InkClipboardFormats enumeration value of the InkDisp object. The default value is ICF_Default.

modes

[in, optional] Specifies the InkClipboardModes enumeration value of the InkDisp object. The default value is ICB_Default.

DataObject

[out, retval] Returns the newly create data object.

Return Value

HRESULT value Description
S_OK Success.
E_POINTER A parameter contained an invalid pointer.
E_INK_EXCEPTION An exception occurred inside the method.

Remarks

If the rectangle clips strokes, those strokes are clipped in the copied data.

It may be useful to copy an InkDisp object to the Clipboard when you only want to copy the properties of the InkDisp object. To copy an InkDisp object to the Clipboard, call the ClipboardCopy method with the strokes parameter set to NULL.

Caution: To avoid potential memory leaks as a result of using the ICB_DelayedCopy flag, you must call the OleFlushClipboard Leave Site or OleSetClipboard Leave Site method. This must be done before the application exits if the last call to the ClipboardCopyWithRectangle method used the ICB_DelayedCopy flag.

When ClipboardCopyWithRectangle is used in ICB_Cut mode, a stroke that gets split into two or more strokes is deleted and new strokes are added in its place.

In addition, the InkAdded and InkDeleted events are generated based on the indices of the strokes. For example, if the strokes at indices 0,1,3,5, and 6 are to be deleted, two events will be generated; one for strokes with indices 0123 and one for strokes with indices 5 and 6. That is, one event for each contiguous set.

This also applies to InkAdded events. An internal algorithm determines the indices of the newly added strokes in the stroke collection and this has an impact on how the InkAdded events are fired as described above.

If the strokes count is queried within the event handler, the result is the total number of strokes added by the whole operation including the strokes that have not yet generated events.

Example

[Visual Basic 6.0]

This Visual Basic 6.0 example copies all of the ink in the InkRectangle, theRectangle, in InkCollector, theInkCollector, to the Clipboard.

        theInkCollector.Ink.ClipboardCopyWithRectangle theRectangle, ICF_Default, ICB_Copy

Applies To