Struct native_windows_gui::Clipboard
source · [−]pub struct Clipboard;
Expand description
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.
Note that NWG clipboard is intentionally keeps things simple and close to the metal. If you want to more robust API, then I recommend you look into https://github.com/DoumanAsh/clipboard-win
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
sourceimpl Clipboard
impl Clipboard
sourcepub fn set_data_text<'a, C: Into<ControlHandle>>(handle: C, text: &'a str)
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
sourcepub fn data_text<C: Into<ControlHandle>>(handle: C) -> Option<String>
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
.
sourcepub fn clear<C: Into<ControlHandle>>()
pub fn clear<C: Into<ControlHandle>>()
Remove the current data in the clipboard
sourcepub fn open<C: Into<ControlHandle>>(handle: C)
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.
sourcepub unsafe fn set_data<D: Copy>(
fmt: ClipboardFormat,
data: *const D,
count: usize
)
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.
sourcepub fn has_format(fmt: ClipboardFormat) -> bool
pub fn has_format(fmt: ClipboardFormat) -> bool
Check if the selected format is available in the clipboard.
sourcepub unsafe fn data<D: Copy>(fmt: ClipboardFormat) -> Option<D>
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.
sourcepub unsafe fn data_handle(fmt: ClipboardFormat) -> Option<ClipboardData>
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.
sourcepub fn count_clipboard_formats() -> u32
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.
sourcepub fn empty()
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
sourcepub fn ownder() -> ControlHandle
pub fn ownder() -> ControlHandle
Return the handle of the window that owns the clipboard
Auto Trait Implementations
impl RefUnwindSafe for Clipboard
impl Send for Clipboard
impl Sync for Clipboard
impl Unpin for Clipboard
impl UnwindSafe for Clipboard
Blanket Implementations
sourceimpl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more