ClientClipboard

Namespace: Wisej.Ext.ClientClipboard

Assembly: Wisej.Ext.ClientClipboard (4.1.0.0)

Represents the Clipboard API implementation, enabling access to the browser's clipboard.

C#

public static class ClientClipboard

VB.NET

Public Class ClientClipboard

The Clipboard interface implements the Clipboard API, providing — if the user grants permission — both read and write access to the contents of the system clipboard. The Clipboard API can be used to implement cut, copy, and paste features within a web application.

Access to the system clipboard is made available through the global Navigator.clipboard property.

Invoking methods of the ClientClipboard class will fail unless the user has approved the required permissions via the Permissions API, specifically the "clipboard-read" and "clipboard-write" permissions as necessary.

Methods

ReadImage(callback)

Asynchronously retrieves the image content from the client's clipboard and invokes the specified callback with the resulting Image.

Parameter	Type	Description
callback	Action<Image>	Callback method that receives the Image result from the client's clipboard.

Throws:

• ArgumentNullException callback is null.

Example:

private void pasteButton_Click(object sender, EventArgs e)
{
    ClientClipboard.ReadImage(image =>
    {
        if (image != null)
            this.pictureBox1.Image = image;
        else
            AlertBox.Show("No image found in the clipboard.");
    });
}

ReadImageAsync()

Returns the image content of the client clipboard.

Returns: Task<Image>. The Image in the client's clipboard, or null if the clipboard doesn't contain an image.

Example:

private async void pasteButton_Click(object sender, EventArgs e)
{
    var image = await ClientClipboard.ReadImageAsync();

    if (image != null)
        this.pictureBox1.Image = image;
    else
        AlertBox.Show("No image found in the clipboard.");
}

ReadText(callback)

Asynchronously retrieves the textual content from the client's clipboard.

Parameter	Type	Description
callback	Action<String>	Callback method that receives the string result from the client's clipboard.

Throws:

• ArgumentNullException callback is null.

ReadTextAsync()

Asynchronously retrieves the textual contents from the system clipboard.

Returns: Task<String>. A task representing the asynchronous operation, containing the string value of the clipboard's contents. If the clipboard is empty or contains non-text data, an empty string is returned.

WriteImage(image, callback)

Writes the specified image to the client clipboard.

Parameter	Type	Description
image	Image	The Image to write to the client's clipboard.
callback	Action	An optional callback action that is invoked when the client's clipboard has been successfully updated. This may be used to perform additional actions after the write operation completes.

Throws:

• Exception Thrown when the client's clipboard cannot be updated due to an internal error.
• ArgumentNullException Thrown when image is null or callback is null.

Example:

The following code copies the image displayed in a PictureBox to the client's clipboard and notifies the user once the browser confirms the update.

private void copyImageButton_Click(object sender, EventArgs e)
{
    ClientClipboard.WriteImage(this.pictureBox1.Image, () =>
    {
        AlertBox.Show("Image copied to the clipboard.");
    });
}

WriteImageAsync(image)

Asynchronously writes the specified image to the client's clipboard in the Png format.

Parameter	Type	Description
image	Image	The Image instance to be written to the client's clipboard. This parameter must not be null.

Returns: Task. A Task that represents the asynchronous write operation.

Throws:

• ArgumentNullException Thrown when image is null.

Example:

The following code copies the image displayed in a PictureBox to the client's clipboard and notifies the user once the browser has completed the operation.

private async void copyImageButton_Click(object sender, EventArgs e)
{
    await ClientClipboard.WriteImageAsync(this.pictureBox1.Image);

    AlertBox.Show("Image copied to the clipboard.");
}

See also: WriteImageAsync

WriteImageAsync(image, format)

Writes the specified image to the client's clipboard using the specified format (default is png).

Parameter	Type	Description
image	Image	The Image to write to the client's clipboard.
format	ImageFormat	The ImageFormat to use for the image encoding.

Returns: Task.

Throws:

• ArgumentNullException image is null.

WriteText(text, callback)

Asynchronously writes the specified text string to the client clipboard.

Parameter	Type	Description
text	String	The text content to be copied to the client's clipboard.
callback	Action	An optional callback method that is invoked when the client's clipboard has been successfully updated.

Throws:

• Exception Thrown when the client's clipboard cannot be updated due to an error.
• ArgumentNullException Thrown when the callback parameter is null.

Example:

The following code copies the content of a text box to the client's clipboard and notifies the user once the browser confirms that the clipboard has been updated.

private void copyButton_Click(object sender, EventArgs e)
{
    ClientClipboard.WriteText(this.textBox1.Text, () =>
    {
        AlertBox.Show("Copied to the clipboard.");
    });
}

WriteText(text)

Writes the specified text string to the client clipboard, allowing the user to copy text from the application directly to their clipboard for use in other applications.

Parameter	Type	Description
text	String	The string of text that will be copied to the client's clipboard.

Example:

ClientClipboard.WriteText("Hello, World!");

WriteTextAsync(text)

Asynchronously writes the specified text to the client's clipboard.

Parameter	Type	Description
text	String	A String containing the text to be copied to the client's clipboard. The text should be non-null and can include any characters supported by the clipboard.

Returns: Task. A Task representing the asynchronous operation. The task will complete once the text has been successfully written to the clipboard.

Throws:

• ArgumentNullException Thrown when text is null.

Example:

await ClientClipboard.WriteTextAsync("Hello, World!");

Events

ClipboardChange

ClientClipboardEventHandler Fired when the user copies, cuts, or pastes content to or from the clipboard.