Docsv3.31.0
Back to API Reference
Interface

IClipboardProvider

abstract

Pluggable system-clipboard provider. The default implementation wraps the active platform (Win32 / NSPasteboard / UIPasteboard / Android ClipboardManager / navigator.clipboard / xclip-xsel-wl-paste); integrators substitute a custom provider for testing, sandboxed clipboards, or platforms outside the shipped set.

Remarks

The interface deliberately mirrors the W3C Async Clipboard API (navigator.clipboard.read() / write(ClipboardItem[])) and Apple's UIPasteboard setItems: shape: items are arrays of (format, payload), not single strings. Multi-format writes are atomic — the consumer on paste picks the richest format it understands. This is the foundation D-005 calls out: shipping the primitives in P1 means P2 features (markdown channel, sanitize-on-paste pipeline, atomic-token UTI registration) extend the interface without breaking integrators. Multi-format is supported on Windows / macOS / iOS / Android / WebGL. Linux reads any offered target through the clipboard tools (xclip -t / wl-paste --type) but can only OFFER one format per write — the tool serves a single target — so multi-format writes keep the plain-text floor (or the richest single format when no plain item is present). See the per-platform matrix on UniTextClipboard.

Implementations(2)

Types that implement IClipboardProvider.

I
IAsyncClipboardProvider
Opt-in extension for clipboard providers that cannot (or should not) read on the caller's thread — WebGL where navigator.clipboard returns Promises, Linux where reads spawn a subprocess. Callers probe via as IAsyncClipboardProvider; providers without it fall through to the sync path wrapped in FromResult<TResult>.
I
IMediaClipboardProvider
Optional IClipboardProvider extension for binary media. File copies arrive as references — a path list (desktop) or URI list (sandboxed platforms) — not as a single blob, so they have their own accessor; raster blobs read through IClipboardProvider.GetData. A provider that does not implement this carries text only.
public abstract bool HasContent()

Whether the clipboard contains at least one item, regardless of format.

public abstract bool HasFormat(ClipboardFormat format)

Reports whether the clipboard currently carries format. This is an availability probe only — implementations must answer it from cheap native presence APIs (Win32 IsClipboardFormatAvailable, NSPasteboard.types, ClipDescription MIME list, X11 TARGETS) and never transfer the payload. Use TryGetText when the payload is wanted; probing then reading doubles the OS transfer. Provider impls that don't understand a format return false regardless of OS-level state.

public abstract string GetText(ClipboardFormat format)

Reads the clipboard payload for format as text. The default path decodes the format's bytes as UTF-8 — appropriate for ClipboardFormat.PlainText / ClipboardFormat.Html / ClipboardFormat.Url. Returns null when the format is not present.

public abstract bool TryGetText(ClipboardFormat format, out string text)

Single-transfer read: fetches format's text payload in one OS clipboard access and reports presence and content together. Returns false (with text null or empty) when the format is absent. The paste pipeline's per-adapter read — never pair HasFormat with GetText for that.

public abstract byte[] GetData(ClipboardFormat format)

Reads the clipboard payload for format as raw bytes. Use for binary formats (P2 image, RTFD) or when the consumer wants control over the text decoding. Returns null when the format is not present.

public abstract void SetItems(IReadOnlyList<ClipboardItem> items)

Writes the entire items list to the clipboard in a single atomic OS-level write. Subsequent reads see all formats simultaneously and the consumer's preferred-format chain selects which one to ingest.

Back to API Reference