Struct native_windows_gui::Clipboard

pub struct Clipboard;

A global object that wraps the system clipboard. It can be used to set or get the system cliboard content.

It's important to keep in mind that there is no way to validate data sent through the clipboard API, as such this wrapper is still mostly unsafe and you must validate the data when reading.

Requires the feature "clipboard"

Writing / Reading text

use native_windows_gui as nwg;

fn clipboard_text(window: &nwg::Window) {
    nwg::Clipboard::set_data_text(window, "Hello!");

    let text = nwg::Clipboard::data_text(window);
    assert!(text.is_some());
    assert!(&text.unwrap() == &"Hello!");
}

Writing / Reading custom data

use native_windows_gui as nwg;

#[repr(C)]
#[derive(Clone, Copy)]
struct Hello {
    foo: usize,
    bar: [u16; 3]
}

fn write_custom_data(window: &nwg::Window) {
    let data = Hello {
        foo: 6529,
        bar: [0, 100, 20]
    };

    nwg::Clipboard::open(window);
    nwg::Clipboard::empty();
    unsafe {
        nwg::Clipboard::set_data(
            nwg::ClipboardFormat::Global("Hello"),
            &data as *const Hello,
            1
        );
    }

    nwg::Clipboard::close();
}

fn read_custom_data(window: &nwg::Window) -> Option<Hello> {
    unsafe {
        nwg::Clipboard::open(window);
        let data = nwg::Clipboard::data(nwg::ClipboardFormat::Global("Hello"));
        nwg::Clipboard::close();
        data
    }
}

fn read_custom_data_handle(window: &nwg::Window) -> Option<Hello> {
    unsafe {
        nwg::Clipboard::open(window);
        let handle = nwg::Clipboard::data_handle(nwg::ClipboardFormat::Global("Hello"));
        let data = match handle {
            Some(h) => {
                let data_ptr: *const Hello = h.cast();
                let data = *data_ptr;
                h.release();
                Some(data)
            },
            None => None
        };

        nwg::Clipboard::close();
        data
    }
}

Implementations

impl Clipboard

pub fn set_data_text<'a, C: Into<ControlHandle>>(handle: C, text: &'a str)

Fill the clipboard with the selected text. The data use the ClipboardFormat::UnicodeText format.

This is a high level function that handles open and close

pub fn data_text<C: Into<ControlHandle>>(handle: C) -> Option<String>

Return the current text value in the clipboard (if there is one). This function will return the text if the clipboard has either the UnicodeText format or the Text format.

If the clipboard do not have a text format OR the text data is not a valid utf-8 sequence, this function will return None.

pub fn clear<C: Into<ControlHandle>>()

Remove the current data in the clipboard

pub fn open<C: Into<ControlHandle>>(handle: C)

Opens the clipboard for examination and prevents other applications from modifying the clipboard content. Another call to close should be made as soon as the application is done with the clipboard.

Parameters: handle: A window control that will be identified as the current "owner" of the clipboard

This function will panic if the control is not HWND based.

pub unsafe fn set_data<D: Copy>(
    fmt: ClipboardFormat,
    data: *const D,
    count: usize
)

Places data on the clipboard in a specified clipboard format.

This method is unsafe because there is no way to ensure that data is valid. If possible, it is recommended to use a higher level function such as set_data_text instead.

If the data will be used across applications, make sure that D has repr(C) for compatibility.

The clipboard must be open when calling this function.

• Note 1: data is copied into a global system allocation. It's ok to discard the data as soon as this function returns.
• Note 2: When copying text, the null byte must be included.

pub fn has_format(fmt: ClipboardFormat) -> bool

Check if the selected format is available in the clipboard.

pub unsafe fn data<D: Copy>(fmt: ClipboardFormat) -> Option<D>

Get the handle to the clipboard data and copy it's data into a new value of type D. This function is very unsafe because it assumes that the handle points to the correct type.

The clipboard must be open when calling this function.

If no data is found with the selected clipboard format, None is returned.

pub unsafe fn data_handle(fmt: ClipboardFormat) -> Option<ClipboardData>

Gets the data handle of the clipboard, lock the memory and return it in a ClipboardData wrapper. The returned data is read-only. The application should copy the data and release the handle as soon as possible.

The clipboard must be open when calling this function.

If no data is found with the selected clipboard format, None is returned.

pub fn count_clipboard_formats() -> u32

A window can place more than one clipboard object on the clipboard, each representing the same information in a different clipboard format. Retrieves the number of different data formats currently on the clipboard.

pub fn empty()

Empty the clipboard data. This is a low-level function and open must have been called first. To only clear the clipboard data use clear

pub fn close()

Close the clipboard after it was opened with the open function.

pub fn ownder() -> ControlHandle

Return the handle of the window that owns the clipboard