Module dui::clipboard

Access to the system clipboard.

The clipboard is a software facility used for short-term data storage and/or data transfer between documents or applications, via copy and paste operations.

The clipboard is user-driven. A window should transfer data to or from the clipboard only in response to a command from the user. A window must not use the clipboard to transfer data without the user's knowledge.

Clipboard Data Formats

A window can place more than one object on the clipboard, each representing the same information in a different clipboard format. Users need not be aware of the clipboard formats used for an object on the clipboard.

Many applications work with data that cannot be translated into a standard clipboard format without loss of information. These applications can create their own clipboard formats. A clipboard format that is defined by an application, is called a registered clipboard format. For example, if a word-processing application copied formatted text to the clipboard using a standard text format, the formatting information would be lost. The solution would be to register a new clipboard format, such as Rich Text Format (RTF).

To register a new clipboard format, use the Clipboard::add_format function. This format can then be used by Clipboard::data and Clipboard::set_data functions.

Standard Formats

IUP gives the user two platform-dependent formats, text and image. If any other is required the user may need to use a custom data format.

Multiple Clipboard Formats

A window can place more than one clipboard object on the clipboard, each representing the same information in a different clipboard format. When placing information on the clipboard, the window should provide data in as many formats as possible.

It's a recommended that clipboard formats that contain the most information should be placed on the clipboard first, followed by less descriptive formats. This is because OS-specific functi- onalities usually iterate on the clipboard data in the same order it was placed and uses the first it is actually able to handle.

For example, suppose a user copies styled text from a word-processing document. The window containing the document might first place data on the clipboard in a registered format, such as RTF. Subsequently, the window would place data on the clipboard in a less descriptive format, such as text.

When the content of the clipboard is pasted into another window, the window retrieves data in the most descriptive format it recognizes. If the window recognizes RTF, the corresponding data is pasted into the document. Otherwise, the text data is pasted into the document and the formatting information is lost.

Explanation borrowed off [MSDN][MSDN]. [MSDN]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms649013%28v=vs.85%29.aspx

Example

Copying

// Sets the user clipboard to have a text in two possible formats, HTML (as a custom format
// using it's MIME type) and text. If the application that receives the paste supports 
// any of these it'll use it.
Clipboard::new()
              .clear()
              .add_format("text/html")
              .set_data("text/html", r"This is <b>my</b> <i>awesome</i> text")
              .set_text("This is my awesome text");

Pasting

let mut clipboard = Clipboard::new();
if let Some(html) = clipboard.add_format("text/html").data("text/html") {
    // Use HTML pasted content.
} else if let Some(text) = clipboard.text() {
    // Use text pasted content.
}

Structs

Clipboard

An element that allows access to the clipboard.