IInkDisp::ClipboardCopyWithRectangle method (msinkaut.h)

Article
10/13/2021

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

Syntax

HRESULT ClipboardCopyWithRectangle(
  [in]           IInkRectangle       *Rectangle,
  [in, optional] InkClipboardFormats ClipboardFormats,
  [in, optional] InkClipboardModes   ClipboardModes,
  [out, retval]  IDataObject         **DataObject
);

Parameters

[in] Rectangle

Specifies the rectangle that contains the strokes to copy to the Clipboard.

[in, optional] ClipboardFormats

Optional. Specifies the InkClipboardFormats enumeration value of the InkDisp object. The default value is ICF_Default.

[in, optional] ClipboardModes

Optional. Specifies the InkClipboardModes Enumeration value of the InkDisp Class object. The default value is ICB_Default.

[out, retval] DataObject

When this method returns, contains a pointer to the newly create data object.

Return value

This method can return one of these values.

Return code	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 or OleSetClipboard 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.

Requirements

Requirement	Value
Minimum supported client	Windows XP Tablet PC Edition [desktop apps only]
Minimum supported server	None supported
Target Platform	Windows
Header	msinkaut.h
Library	InkObj.dll