ui::Clipboard¶

Header: winui/ui/Clipboard.hpp.

The system clipboard as a control or app sees it: text, a bitmap and storage items.

The library provides the implementation. There is one for the whole process, returned by ui::clipboard(). TextBox's Ctrl+C/X/V and every other control go through it, and app code uses it the same way, also before ui::run(). A test swaps in a double with ui::testing::set_clipboard(). Non-copyable. The library owns it.

Example:

ui::Clipboard& clipboard = ui::clipboard();
clipboard.set_text("Copied!");
if (clipboard.contains(ui::StandardDataFormat::Bitmap))
{
    const std::optional<ui::Bitmap> picture = clipboard.bitmap();
}
// Keep the subscription alive for as long as the notifications are wanted.
ui::ButtonControl paste_button{"Paste"};
ui::Subscription  paste_watch = clipboard.content_changed().observe([&](const std::uint64_t&) {
    paste_button.set_enabled(clipboard.contains(ui::StandardDataFormat::Text));
});

Clipboard¶

Clipboard() = default

Clipboard¶

Clipboard(const Clipboard&) = delete

operator=¶

Clipboard& operator=(const Clipboard&) = delete

~Clipboard¶

virtual ~Clipboard() = default

set_text¶

virtual void set_text(const std::string& text) = 0

Replace the clipboard's contents with text.

text¶

virtual std::optional<std::string> text() const = 0

The clipboard's current text, or nullopt if it holds no text (empty, or a non-text format like an image). Holding an empty string returns "", not nullopt.

set_content¶

virtual bool set_content(const ClipboardContent& content, const ClipboardContentOptions& options = {}) = 0

Replace the clipboard's contents with every part of content that is set. False when the clipboard could not be opened (another app holds it) or content has nothing in it; the old contents are then left alone.

Works from any thread. A large bitmap takes a while to encode, so an app copying one can call it from a background thread to keep its window responsive.

bitmap¶

virtual std::optional<Bitmap> bitmap() const = 0

The clipboard's picture, or nullopt when it holds none or it cannot be decoded.

storage_items¶

virtual std::vector<std::filesystem::path> storage_items() const = 0

The paths on the clipboard; empty when it holds none.

requested_operation¶

virtual DataPackageOperation requested_operation() const = 0

What the app that copied the storage items wants done with them, such as Move after a cut in a file manager. None when it said nothing.

contains¶

virtual bool contains(StandardDataFormat format) const = 0

Whether the clipboard holds data in format.

available_formats¶

virtual std::vector<std::string> available_formats() const = 0

The name of every format on the clipboard, in the order its owner put them there. These are the system's format names, such as "CF_UNICODETEXT", "PNG" or "CF_HDROP". Empty when the clipboard is empty.

clear¶

virtual void clear() = 0

Empty the clipboard.

is_history_enabled¶

virtual bool is_history_enabled() const = 0

Whether the user has turned on the clipboard history (Win+V).

is_roaming_enabled¶

virtual bool is_roaming_enabled() const = 0

Whether the user has turned on syncing the clipboard across devices.

content_changed¶

const Property<std::uint64_t>& content_changed()

A count of clipboard changes. It goes up every time any app, this one included, changes the clipboard. Observe it to get notified of changes, and drop the Subscription to stop. The clipboard is only watched from the first call on.

start_watching¶

virtual void start_watching()

Starts watching for clipboard changes. Called once, on the first content_changed().

raise_content_changed¶

void raise_content_changed()

Advances content_changed() by one; an implementation calls it on every change it sees, its own writes included.