Ink.ClipboardCopy Method

Ink.ClipboardCopy Method

Copies the Strokes collection contained in the specified rectangle to the Clipboard .

Definition

Visual Basic .NET	Public Function ClipboardCopy( _ ByVal copyRectangle As Rectangle, _ ByVal formats As InkClipboardFormats, _ ByVal modes As InkClipboardModes _ ) As IDataObject
C#	public IDataObject ClipboardCopy( Rectangle copyRectangle, InkClipboardFormats formats, InkClipboardModes modes );
Managed C++	public: IDataObject* ClipboardCopy( Rectangle *copyRectangle, InkClipboardFormats *formats, InkClipboardModes *modes );

Parameters

> > > > > > >

copyRectangle	System.Drawing.Rectangle. The rectangle that contains the Strokes collection to copy to the Clipboard .
formats	Microsoft.Ink.InkClipboardFormats. A member of the InkClipboardFormats enumeration that specifies the format for the Ink object. The default value is Default. None0 Specifies a flag that can be used to verify whether any formats are present by checking against it. InkSerializedFormat1 Specifies ink is encoded in Ink Serialized Format (ISF). This is the most compact persistent representation of ink. Although it often contains only ink data, is extensible. Applications can set custom attributes (identified by a globally unique identifier (GUID)) on an Ink object, stroke, or point. This allows an application to store any kind of data or metadata it requires as an attribute in an ISF stream. SketchInk2 Specifies ink is not expected to form words, but rather is interpreted as a picture. This is also useful for representing multiple words. TextInk6 Specifies ink is expected to form words. It allows the ink to be converted to text. The recognized text is either the alternate with the greatest confidence rating or another alternate chosen from a list. This is useful for representing a single word. This format includes the SketchInk format. EnhancedMetafile8 Specifies the enhanced metafile to play to create the background. The metafile must remain valid for as long as it is used to render the ink background. Metafile32 Specifies ink is stored as a metafile or a list of commands that can be played back to draw a graphic. Bitmap64 Specifies the bitmap to use as the background. The bitmap device context must remain valid for as long as it is used to render the ink background. PasteMask7 Specifies the formats that can be used for pasting. This format includes the TextInk, SketchInk, and InkSerializedFormat formats. CopyMask127 Specifies the formats that are copied to the Clipboard through ink. Default127 The CopyMask format.
modes	Microsoft.Ink.InkClipboardModes. A member of the InkClipboardModes enumeration that specifies the mode for the Ink object. The default value is Default. > > > > > > > > > > > > > > > > > > > > > > > > > Copy0 Copies the ink to the Clipboard. Cut1 Cuts the ink and copies it to the Clipboard. ExtractOnly48 Does not copy the ink to the Clipboard. Typically, use this option if you want to add something else, such as text, to the ink before you copy it to the Clipboard. DelayedCopy32 Uses delayed rendering to reduce the amount of data that is stored on the Clipboard. The data is rendered when a paste request is made. Default0 The Copy mode.

Return Value

System.Windows.Forms.IDataObject. Returns the data object to be created. The default value is null (Nothing in Microsoft® Visual Basic® .NET).

Exceptions

ObjectDisposedException : The Ink object is disposed.
ThreadStateException :

Remarks

If the rectangle clips Stroke objects, the corresponding Stroke objects are clipped in the copied data.

It may be useful to copy an entire Ink object to the Clipboard when you want to copy all of the properties of the Ink object. To copy an Ink object to the Clipboard , call the ClipboardCopy(Strokes,InkClipboardFormats,InkClipboardModes) method with the strokes parameter set to null (Nothing in Microsoft® Visual Basic® .NET).

When you use the ClipboardCopy(Rectangle,InkClipboardFormats,InkClipboardModes) method in Cut mode, a Stroke object that gets split into two or more strokes is deleted and new strokes are added in its place.

Ink.InkDeleted events are generated based on the indices of the Stroke objects within the Strokes collection. For example, if the Stroke objects at indices 0, 1, 2, 3, 5, and 6 are to be deleted, two events are generated. One event is generated for Stroke objects with indices 0, 1, 2, and 3; and one event is generated for Stroke objects with indices 5 and 6. That is, there is one event for each contiguous set. This also applies to InkAdded events; however, an internal algorithm determines the indices of the newly added Stroke objects in the Strokes collection and has an impact on how the InkAdded events are fired.

If you query for the Strokes collection's Count property from within the event handler, the result is the total number of Stroke objects added by the whole operation, including the Stroke objects that have not yet generated events.

Caution: To avoid potential memory leaks as a result of using the DelayedCopy flag, call the SetDataObject method of the Clipboard object. This must be done before the application exits if the last call to the ClipboardCopy method used the DelayedCopy flag.

Security Alert: If using under partial trust, this method requires UIPermissionClipboard.OwnClipboard permission. See Security And Trust for more information.

Examples

[C#]

This C# example copies all of the ink from the Rectangle structure, theRectangle, into the InkCollector object, theInkCollector to the Clipboard .

try
{
    theInkCollector.Ink.ClipboardCopy(theRectangle,
        InkClipboardFormats.Default, InkClipboardModes.Copy);
}
catch
{
    // Place exception handling code here.
}

[Visual Basic .NET]

This Visual Basic .NET example copies all of the ink from the Rectangle structure, theRectangle, into the InkCollector object, theInkCollector to the Clipboard .

Try
    theInkCollector.Ink.ClipboardCopy(theRectangle,
        InkClipboardFormats.Default, InkClipboardModes.Copy)
Catch
    'Place exception handling code here.
End Try

See Also

• ClipboardPaste Method